Errors & limits

Errors use ordinary HTTP status codes and a stable JSON body. Retry only what is safe to retry.

Error body

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests for this key",
    "retry_after": 4
  }
}

Codes

StatuscodeMeaning / what to do
400invalid_requestMalformed body or unknown field. Fix the payload.
401invalid_keyKey missing, revoked, or wrong environment.
403scope_deniedKey lacks the scope for this endpoint.
404not_foundNo job with that id, or it expired (48 h).
409duplicate_jobSame idempotency key is still running.
413too_largeAbove 60 MB or 500 pages: split the file.
422unreadableEncrypted or image-only PDF with no text layer — try /v1/ocr.
429rate_limitedBack off using retry_after.
5xxupstreamRetry with jitter; report the request id if it persists.

Rate limits

Limits are per key, per minute, and count pages rather than calls:

Each response carries X-RateLimit-Remaining and X-RateLimit-Reset. Persist the latter instead of computing it.

Idempotency

Send Idempotency-Key on POSTs that cost credits. Replaying the same key within 24 h returns the original result rather than re-running the job — useful when a timeout leaves you unsure whether the work landed.