Errors and limits

The error envelope

Every error from the parse API is a flat JSON object with two keys, and sometimes a third:

{"error": "You do not have any more credits. Please contact sales@affinda.com", "code": "no_credits"}

• error is a message that is safe to show a person. It can change without notice.
• code is a stable machine-readable identifier. Branch on this, never on the message or on the status alone.
• retryAfterSeconds appears when waiting is the right response. The Retry-After HTTP header carries the same number.

This envelope belongs to the parse API. The console's own endpoints, and the wider Affinda platform API at app.affinda.com, use a different and more nested error format. If you use both, do not share error-handling code between them.

Errors raised by the parser itself, rather than by the API in front of it, are relayed to you unchanged with their own status. That is why the code values below come from two families.

Status codes

Retry 429, 502, 503 and 504. Do not retry 4xx codes that describe the request itself: the same request will fail the same way.

What the parser accepts

The cloud API is deliberately lenient. If a file might hold text, it is attempted.

Three things are rejected rather than attempted:

• Encrypted documents, with 422 password_protected_document. Nobody can read them, including us.
• Empty files. A zero-byte upload is answered 400 missing_file, and a file that holds no readable text at all is answered 422 unparseable_document.
• Legacy PowerPoint (.ppt), with 415 unsupported_format.

Anything else is attempted. A file that turns out to hold no usable text still returns 200, with very little in data and a low meta.document.extractionQuality.band. Checking that band is how you tell a thin result from a good one. A self-hosted container with OCR switched off also rejects images, with 415 unsupported_format, because there is nothing to read them with.

Two limits that truncate quietly rather than failing:

• Only the first 20 pages of a document contribute fields.
• OCR reads the first 3 pages. When there were more, meta.ocr.truncated is true and meta.document.warnings carries ocr_truncated.

Size limit

A file may be up to 20 MB. Larger files are rejected with 413 file_too_large before the parser is called, so they cost nothing. The size is checked against the declared Content-Length, against the multipart part, and again against the bytes actually received.

Rate limits

These are an abuse floor rather than a quota: normal use does not come near them. Going over gives 429 rate_limited. If you need more, contact sales@affinda.com.

The free tool on our website at https://www.affinda.com/free-resume-parser has its own generous daily fair-use cap, per IP address. It is a tool for people, not an API to build on.

Credits

One successful parse costs one credit, however many pages the document has. A parse that fails costs nothing: the credit is charged after the parser returns, and every error path above either never reaches the parser or never charges.

New accounts start with 1,000 free credits, valid for 14 days. Credits you buy are separate and get their own expiry at purchase.

The X-Credits-Remaining response header carries your balance after the parse was charged. It is omitted if the balance could not be read, so treat its absence as "unknown" rather than "zero".

When credits run out, or when they expire, parses stop with 402 no_credits. Nothing is parsed and nothing is charged. Buy more on the console's Billing screen at /billing.

Response headers

The three X-Parser-* headers are hints for a client that wants to pace itself. They are not promises, and they can change from one response to the next.