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 a rate limit. Almost always the hourly API limit on your X-API-Key traffic; the customer portal has its own separate per-person limit that ordinary use does not reach.

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. The hourly API limits 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, and the customer portal is not charged against these limits. Only requests carrying your API key count.
  2. If you saw this in the customer portal rather than from an integration, it is not your API quota: portal traffic is never charged against the API limits. Two things can cause it. On pages you use while signed in, the per-person limit is generous enough that ordinary use never reaches it, so a repeated 429 usually means something is retrying in a loop. On pages that do not require signing in (the sign-up wizard, the public status page, the sales chat), the limit is counted per network address, so several people on one office or campus network can reach it together. Either way: wait a minute and try again, and contact support if it keeps happening.
  3. Implement exponential backoff in integration scripts.
  4. Reporting API requests have their own allowance: 600 requests an hour per account on every plan, separate from the API limits above (the API add-on does not change it). A Reporting API 429 says "bucket": "reporting" in its body. A 429 with the code reporting_busy is different: other Reporting API requests for your account are still being worked on, so wait 5 seconds and send pages one after another; it does not count against the allowance. See Reporting API.
  5. 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.

Reporting API error codes#

The Reporting API answers errors as {"error": "<code>", "message": "<one sentence>"}. The codes you are most likely to see:

  • api_key_in_url (400): an API key was put in the request's URL. Revoke that key in the portal, create a new one and send it in the X-API-Key header.
  • reporting_busy (429): other Reporting API requests for your account are still being worked on. Wait 5 seconds and send pages one after another.
  • values_changed (409): Include values was turned on or off for the key while you were paging through a dataset. Start again without a cursor.
  • cursor_expired (410): the day your paging started from has left the 90-day history. Start again without a cursor.
  • no_check_on_date (404): there is no completed daily check for the date you asked for. Leave out date to get the latest check.
  • account_suspended (402): the account is suspended. Reporting data is available again once the account is active.

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.