API
Errors and limits
One error envelope everywhere, stable machine-readable codes, and rate limits that scale with your plan.
The error shape
Every error, on every endpoint, is the same envelope: a short machine-readable code to branch on and a human-readable message to log.
{
"error": {
"code": "upload_too_large",
"message": "file must be under 20 MB"
}
}Error codes
| Status | Code | When |
|---|---|---|
| 401 | unauthenticated | No bearer token on the request. |
| 401 | invalid_api_key | The key is wrong or has been revoked. |
| 404 | not_found | The document id does not exist in your workspace. |
| 413 | upload_too_large | The file is over 20 MB. |
| 415 | upload_type | The file is not a PDF, PNG, or JPEG. |
| 429 | rate_limited | Too many requests. Back off and retry. |
| 500 | internal_error | Something failed on our side. Safe to retry. |
| 503 | storage_unavailable | File storage is briefly unavailable. Retry with backoff. |
Rate limits
Every plan has a request rate limit sized well above its included document volume; you will hit your document quota long before the rate limit in normal use. When you do exceed it, requests answer 429 with rate_limited. Back off for a few seconds and retry. Higher tiers carry higher limits; see pricing.
Failed extractions
A failed extraction is not an HTTP error. The upload succeeds, and the extraction later lands in status failed with an error_message explaining why. Failed extractions do not count against your included documents.