Error Reference

This page explains the most common errors you may encounter while using OpenBoxes Lift, what causes them, and how to resolve them.

HTTP Error Codes#

401 Unauthorized#

What it means: The server does not recognize your identity. You are either not logged in or your session has expired.

Common causes:

  • Your session timed out due to inactivity — your OpenBoxes instance signs you out after 2 hours without activity; the customer portal at app.openboxes.cloud after 14 days idle (30 days maximum)
  • You opened OpenBoxes in a new browser tab or window where you are not logged in
  • Your API key or credentials are incorrect (for integrations)

How to fix:

  1. Log in again at your instance URL.
  2. If using the API, verify your credentials or API key are correct.
  3. If this happens immediately after logging in, clear your browser cookies for *.openboxes.cloud and try again.

403 Forbidden#

What it means: You are logged in, but your account does not have permission to perform this action.

Common causes:

  • You are trying to access an admin-only feature with a non-admin account
  • Your OpenBoxes role does not include the required permission (e.g., creating or batch-editing products requires the Admin role; where purchase-order approval is switched on, approving requires the Purchase Approver role)
  • You are attempting to access another organization's data

How to fix:

  1. Contact your organization's OpenBoxes administrator to request the appropriate role.
  2. Verify you are logged into the correct instance (check the URL).
  3. If you believe you should have access, contact support.

404 Not Found#

What it means: The page or resource you requested does not exist.

Common causes:

  • A bookmarked URL that is no longer valid (e.g., a deleted product or shipment)
  • A typo in the URL
  • Accessing an API endpoint that does not exist or has been renamed

How to fix:

  1. Navigate to the page using the OpenBoxes menu instead of a bookmark.
  2. If using the API, check the API documentation for the correct endpoint path.
  3. If you followed a link within OpenBoxes and got a 404, the referenced record may have been deleted by another user.

500 Internal Server Error#

What it means: Something went wrong on the server. This is not caused by anything you did.

Common causes:

  • A temporary server issue
  • A bug triggered by a specific combination of data or actions
  • A database query that failed unexpectedly

How to fix:

  1. Wait a minute and try again — many 500 errors are transient.
  2. If the error persists, try a different action or page to determine if the issue is isolated.
  3. If it keeps happening, submit a support ticket with the URL, the action you were performing, and the approximate time. This helps us find the error in our logs.

Tip: If you see a 500 error during a data import or bulk operation, the operation may have partially completed. Check your data before retrying to avoid duplicates.

502 Bad Gateway#

What it means: The gateway received an invalid response from the backend service.

Common causes:

  • The OpenBoxes application is restarting (e.g., after an update)
  • Temporary network issue between platform components

How to fix:

  1. Wait 1--2 minutes and refresh the page. This often resolves after a restart completes.
  2. Check the System Status page for any ongoing maintenance.

504 Gateway Timeout#

What it means: The server took too long to respond to your request.

Common causes:

  • A large data export or report that exceeds the timeout threshold
  • A complex search query across a large dataset
  • High system load during peak usage

How to fix:

  1. Narrow your request — use date filters, limit the number of records, or export in smaller batches.
  2. Try again during off-peak hours.
  3. If timeouts are frequent, you may benefit from upgrading to a Dedicated tier with more resources.

429 Too Many Requests#

What it means: You have exceeded the API rate limit.

Common causes:

  • An integration script making too many requests in a short period
  • Multiple browser tabs triggering simultaneous API calls
  • A misconfigured polling interval (e.g., polling every second instead of every minute)

How to fix:

  1. Slow down your request rate. Limits are hourly and apply per account (shared across all of your API keys): 1,000 requests per hour on Shared, 25,000 per hour on Dedicated, and 50,000 per hour on Enterprise. Normal use of the OpenBoxes web application is never rate-limited — only requests carrying your API key count.
  2. Implement exponential backoff in integration scripts.
  3. Every API response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (a Unix timestamp) headers, and a 429 response also carries Retry-After (seconds) — wait that long, or until the reset time, before retrying.

Application Errors#

"Session Expired"#

Your session timed out — OpenBoxes instances sign you out after 2 hours of inactivity, and the customer portal after 14 days idle. Click Log In to re-authenticate. Any unsaved form data may be lost.

Tip: Save your work frequently, especially on long forms. OpenBoxes does not auto-save drafts.

"You do not have permission to perform this action"#

Same as a 403 error — your user role lacks the required permission. Contact your OpenBoxes administrator.

"Import failed: Invalid file format"#

The file you uploaded is not in the expected format. Ensure you are uploading a .csv file saved as UTF-8 with the correct column headers. See Common Issues for detailed import troubleshooting.

"Unable to connect to server"#

Your browser cannot reach the OpenBoxes Lift servers. Check your internet connection, verify that *.openboxes.cloud is not blocked by your firewall or proxy, and try again.