Document extraction API errors and limits

The two error shapes

Requests refused before they reach an endpoint, for authentication or limits, return error and code. Branch on code, and treat error as a message for people.

{ "error": "Too many submissions.", "code": "rate_limited", "retry_after_seconds": 12 }

Errors from an endpoint itself return detail. It is a string for 400, 401, 403, 404 and 409, and a list of issues for 422.

{ "detail": "This PDF could not be read." }

{
  "detail": [
    { "loc": ["body", "file"], "msg": "field required", "type": "value_error" }
  ]
}

Error codes

Other errors

When a run fails

A request can succeed and the run still fail later. In that case the poll returns 200 with status: "failed" and a short generic error, and the pages are given back. Check status as well as the HTTP code.

The exception is a document outside the supported types, such as a CV or a letter, which adds a specific code and an explanation written for you to show as it is. To process one of these, build a workflow in the dashboard.

{
  "status": "failed",
  "error_code": "unsupported_document_type",
  "error": "This document was identified as 'Other', which is not a supported document type. …"
}

Monthly page quota

Your quota is counted in pages per calendar month and shared by everyone in your organisation and every key. A PDF counts its pages; anything else counts as 1. Pages are charged on submit and given back if the run fails. The free Starter plan includes 100 pages a month. A document that doesn't fit is refused whole with 429 quota_exceeded, and the error includes pages_used, pages_limit and resets_at.

Check your usage

GET /v1/usage returns your plan, what you've used this period, when the quota resets and your rate limit. It works with an API key, so your code can check pages_remaining before sending a large batch.

curl "$DOCREFINERY_API/v1/usage" \
  -H "Authorization: Bearer $DOCREFINERY_API_KEY"

{
  "plan": "free",
  "period": "2026-11",
  "pages_used": 42,
  "pages_limit": 100,
  "pages_remaining": 58,
  "resets_at": "2026-12-01T00:00:00Z",
  "requests_per_minute": 30,
  "api_keys_enabled": true
}

Rate limit

The rate limit counts document submissions per minute, for the whole account. Starter accounts get 30 a minute, and requests_per_minute in the usage response gives yours. POST responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, so a batch job can slow down before it is refused. Over the limit you get 429 rate_limited with the wait in seconds.

Upload size limit

A file can be up to 100 MB. A larger upload is refused with 413 payload_too_large before it is read, so check the size on your side first and avoid sending a file that can't succeed.

Other limits on Starter

The pricing page lists up to 4 documents processing at once and 7-day data retention on Starter, so collect results promptly. Paid plans are quoted by sales and run more documents in parallel.

When to retry

• Retry after waiting: 429 rate_limited, for as long as retry_after_seconds says.
• Retry once after 2 seconds: 503 auth_unavailable.
• Don't retry unchanged: 400, 401, 403, 404, 413, 422 and 429 quota_exceeded.
• Failed run: a poll that reports failed won't change. Submit the document again if you want another attempt; the failed run's pages were given back.