Reference

Errors and rate limits

REST errors use this envelope. Keep the request ID for support and never log your API key:

Start with code and requestId

The stable code tells your program what happened. The human-readable message explains this request. Save requestId when contacting support.

JSON error response

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "The API key is missing, invalid, or revoked.",
    "requestId": "req_..."
  }
}

Fix authentication and plan errors

For 401, check that the header begins with Bearer followed by one space and an active key. For 403, check the account plan and the scopes selected when the key was created.

Fix upload-state errors

For 409 or 422, confirm the PUT finished, Content-Type matches, and the uploaded byte count equals sizeBytes. Create a fresh upload job if the temporary URL expired.

Code	HTTP	Meaning
BAD_REQUEST	400 / 409	HTTP 400 means the request body is invalid; HTTP 409 means the upload cannot be completed in its current state.
UNAUTHORIZED	401	The API key is missing, invalid, or revoked.
PAID_PLAN_REQUIRED	403	The account does not have an eligible paid plan.
INSUFFICIENT_SCOPE	403	The API key does not include the required scope.
NOT_FOUND	404	The owned upload, file, or share was not found.
UPLOAD_NOT_READY	409	The uploaded object is not ready for completion.
FILE_TOO_LARGE	413	The file exceeds the applicable size limit.
OBJECT_VALIDATION_FAILED	422	The uploaded object failed validation.
QUOTA_EXCEEDED	429	The upload quota is exhausted.
RATE_LIMIT_EXCEEDED	429	The API request rate is exhausted.
SERVICE_UNAVAILABLE	503	A required service is temporarily unavailable.

Rate-limit headers

Retry 429 only after Retry-After. Retry temporary 503 errors with exponential backoff. Do not automatically retry invalid 400, 401, or 403 requests.