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
| Status | code | Meaning / what to do |
|---|---|---|
| 400 | invalid_request | Malformed body or unknown field. Fix the payload. |
| 401 | invalid_key | Key missing, revoked, or wrong environment. |
| 403 | scope_denied | Key lacks the scope for this endpoint. |
| 404 | not_found | No job with that id, or it expired (48 h). |
| 409 | duplicate_job | Same idempotency key is still running. |
| 413 | too_large | Above 60 MB or 500 pages: split the file. |
| 422 | unreadable | Encrypted or image-only PDF with no text layer — try /v1/ocr. |
| 429 | rate_limited | Back off using retry_after. |
| 5xx | upstream | Retry with jitter; report the request id if it persists. |
Rate limits
Limits are per key, per minute, and count pages rather than calls:
- Sandbox — 60 requests/min, 100 pages/min
- Production — 600 requests/min, 1 000 pages/min
- Burst — up to 2× for ten seconds, then steady state
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.