Errors, retries, and limits

Use HTTP status, the structured message, and the request ID to decide whether a request should be fixed, retried, or reported.

Error response

{
  "code": 403,
  "message": {
    "code": "insufficient_scope",
    "required": "assets:write"
  },
  "requestId": "req_01J..."
}

Status codes

NameTypeDescription

400fix request

Malformed input, conflicting authentication methods, or an invalid operation.

401authenticate

Missing, invalid, expired, or revoked credential.

403authorize

The actor lacks workspace access, role, required scope, or an active API entitlement.

404not found

The resource does not exist in the active workspace.

409refresh state

The resource changed or is already processing. Read it again before retrying.

410expired

The upload session or conversion expired and must be recreated.

413size limit

The source is larger than the active upload or conversion limit.

415file type

The declared MIME class does not match the detected bytes.

422validation

A field, path, option, or requested state transition is invalid.

429backoff

A rate, concurrency, or usage limit was reached.

500retry

Unexpected server failure. Retry safe reads and idempotent writes with backoff.

API entitlement codes

NameTypeDescription

subscription_inactive403

The paid plan is not active. Existing keys remain revocable but cannot authenticate.

api_access_disabled403

API access was disabled for this workspace by an administrative override.

rate_limit_exceeded429

A short-window, daily, monthly, or expensive-operation allowance was reached. Inspect Retry-After before retrying.

Retry policy

Retry 429 and transient 5xx responses with exponential backoff and jitter. Do not retry validation errors unchanged. Upload completion is the only endpoint with an explicit Idempotency-Key contract.

Response headers

NameTypeDescription

X-Request-Idstring

The validated client request ID or a server-generated ID. Use printable ASCII no longer than 128 characters.

RateLimitstring

Limit, remaining requests, and reset for the active window.

RateLimit-Policystring

The active rate policy.

X-RateLimit-Limitinteger

Maximum requests in the active window.

X-RateLimit-Remaininginteger

Requests remaining in the active window.

X-RateLimit-Resetinteger

Seconds until the active window resets.

Retry-Afterinteger

Seconds to wait after a 429 response.

Include the request ID, route, status, and timestamp when reporting an API failure. Never include the raw API key or signed token.

Need another path?

Open dashboard Read engineering notes