Error Handling

All errors are JSON and include a stable error code plus request_id.

Error shape

{
  "error": "Insufficient quota",
  "code": "quota_exceeded",
  "request_id": "req_123"
}

Common codes

• invalid_request: request body, file, or parameter validation failed
• unauthorized: API key missing, invalid, or revoked
• quota_exceeded: account has insufficient credits/quota
• rate_limited: request frequency or concurrency limit exceeded
• not_found: job/document does not exist or is not accessible
• internal_error: unexpected server-side failure

Recommended retry strategy

• Retry 429 and transient 5xx with exponential backoff and jitter.
• Do not retry 400 until request payload is fixed.
• Do not retry 401 until key/config is fixed.
• For 402 quota_exceeded, stop processing and trigger billing flow.

Example retry backoff

• Attempt 1: wait 1s
• Attempt 2: wait 2s
• Attempt 3: wait 4s
• Attempt 4: wait 8s
• Add random jitter (+/- up to 20%)

Support workflow

Persist request_id in your logs so support can trace issues quickly.