OCRRouter

Errors and limits

Errors share one shape: a machine-readable code and a message you can show to a person. Failed requests are never charged.

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.
503 model_unavailablePOST /v1/ocr
No model in the chain (model plus fallbacks, or the models auto picks) can be called right now. Add a fallback that is available or try another model.

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"])