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 (default: 30 minutes)
  • 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 user role does not include the required permission (e.g., approving purchase orders requires the Manager 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. Respect the rate limits for your tier: 60/min (Shared), 300/min (Dedicated).
  2. Implement exponential backoff in integration scripts.
  3. The Retry-After header in the response tells you how many seconds to wait before retrying.

Application Errors

"Session Expired"

Your session timed out. 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.