Error shape
{"error": {"code": "insufficient_credits","message": "This request needs up to 72 credits and your ba…"}}Some errors add fields next to code and message: all_models_failed adds id and attempts, file_too_large adds limit_mb. A 429 has a Retry-After header in seconds.
Error codes
400 invalid_requestPOST /v1/ocr, POST /v1/files- The body is not JSON, a parameter has the wrong type or value, or not exactly one of file_url, file_base64 and file_id was sent. The message names the field.
400 unknown_modelPOST /v1/ocr- model or a fallbacks entry is not a model ID. GET /v1/models lists them.
400 unsupported_filePOST /v1/ocr, POST /v1/files- The file is not a PDF, PNG, JPG, WebP or GIF (public links on /v1/files accept any type).
400 empty_filePOST /v1/ocr, POST /v1/files- The file has 0 bytes, or the PDF has no pages.
400 unreadable_pdfPOST /v1/ocr- The PDF could not be opened. It may be damaged or encrypted.
400 invalid_pagesPOST /v1/ocr- pages does not look like 1-5,8, or asks for a page past the end of the file.
400 invalid_file_urlPOST /v1/ocr- file_url is not a valid public http or https address.
400 file_fetch_failedPOST /v1/ocr- We could not download file_url, or it answered with an HTTP error. The message includes the status.
401 missing_api_keyAll endpoints that need a key- No Authorization: Bearer <key> header.
401 invalid_api_keyAll endpoints that need a key- The key is wrong or has been revoked.
402 insufficient_creditsPOST /v1/ocr- Your balance is below the most this request could cost (pages x the dearest model in the chain). Add credits or pick a cheaper model.
402 key_limit_reachedPOST /v1/ocr- This key has a credit limit and the request would go over it.
402 free_limit_reachedPOST /v1/ocr (no account)- Requests without an account are limited to 3 pages a day.
404 file_not_foundPOST /v1/ocr, DELETE /v1/files/{id}- No upload with this file_id, or it has expired (uploads are kept 24 hours).
404 not_foundGET /v1/requests/{id}- No request with this ID under your account.
413 file_too_largePOST /v1/ocr, POST /v1/files- The file is over 20 MB for OCR, or over the public link limit. Upload errors include limit_mb and subscriber_limit_mb.
413 too_many_pagesPOST /v1/ocr- The document has more pages than any available model in the chain accepts. Send a range with pages.
413 direct_upload_requiredPOST /v1/files- The upload is larger than one request can carry. Use the upload box on the site. Includes limit_mb.
429 rate_limitedPOST /v1/ocr, POST /v1/files- More than 60 requests a minute on one key. Wait for the Retry-After header.
429 temporary_key_limitPOST /v1/keys/temporary- One temporary key per IP address per day.
502 all_models_failedPOST /v1/ocr- Every model in the chain failed. The body also has id and attempts, each with its error. You are not charged.
Limits
- File size
- 20 MB per file for OCR, whether sent as file_url, file_base64 or file_id.
- File types
- PDF, PNG, JPG, WebP and GIF. DOCX is not read by the API yet.
- Pages
- Each model has its own maximum (max_pages in GET /v1/models). Use pages to send a range of a longer PDF.
- Rate
- 60 requests per minute per API key on POST /v1/ocr and POST /v1/files.
- Timeout
- Each model attempt gets 120 seconds. The next model in the chain then gets its own 120 seconds.
- Fallbacks
- Up to 5 extra model IDs. With model auto, the chain is the top 3 models for the chosen route.
- Uploads
- file_id from POST /v1/files works for 24 hours.
- Without an account
- 3 pages a day. A temporary key from POST /v1/keys/temporary has 50 credits.
Retrying
Retry 429 after Retry-After and 502 with another model or with fallbacks. Do not retry 4xx errors other than 429 without changing the request.
import time, requests
def ocr(body, key, tries=3):
for i in range(tries):
r = requests.post("https://api.ocrrouter.ai/v1/ocr", json=body,
headers={"Authorization": f"Bearer {key}"})
if r.status_code == 429:
time.sleep(int(r.headers.get("Retry-After", 60)))
continue
if r.status_code == 502: # every model failed, nothing was charged
body = {**body, "model": "auto"}
continue
r.raise_for_status()
return r.json()
raise RuntimeError(r.json()["error"]["message"])