Errors & retries

Problem responses, request IDs and retry behavior.

Problem responses

Errors use application/problem+json. Retain the body’s requestId or the X-Request-ID response header when investigating a failed request.

Example · missing credential

{
  "type": "https://api.boxobserver.com/problems/authentication-required",
  "title": "Request rejected",
  "status": 401,
  "detail": "A bearer API key or Clerk session token is required.",
  "requestId": "example-request-id"
}

Status codes

Status	Meaning	Client action
400	Invalid filter, ID, cursor or date range	Correct the request.
401	Missing, invalid, expired or revoked credential	Obtain a valid credential; do not loop retries.
403	Origin or access rejected	Check access and browser-origin configuration.
404	Resource unavailable within your access, or route not found	Check the path and identifier.
429	Rate limit exceeded	Respect Retry-After.
500	Unexpected server error	Use a bounded retry and retain the request ID.
503	Public access disabled, dependency unavailable or configuration missing	Check the response detail and current access status.

Retries

All documented resource operations are GET requests. Retry transient failures with exponential backoff and jitter, and cap both attempts and total elapsed time. Do not retry validation or authorization failures unchanged.

If the service temporarily returns Public data access is not enabled., the operational kill switch is active. Repeated requests will not enable access.

Private data-service calls have a ten-second timeout and receive request cancellation. A browser cancelling a request does not guarantee that a database query already executing is stopped.

CORS and errors

A disallowed browser origin receives 403. For allowed origins, preflight permits GET and OPTIONS with Authorization and Content-Type headers. Keep tokens in headers and never put them in a URL.