Errors

Errors come back in one envelope with a stable code. Branch on the code: messages get reworded, codes do not.

The envelope#

json

{
  "error": {
    "code": "not_a_bank_statement",
    "message": "This document does not look like a bank or card statement.",
    "documentId": "doc_5f2a9c4b1e77d0a3c8b6e412"
  }
}

documentId is present whenever we got far enough to allocate one. Quote it in a support question. Some errors carry extra fields, such as reason on a 409.

Every code#

400empty_body

No PDF arrived.

401missing_key

No Authorization header on the request.

401invalid_key

The key is unknown or has been revoked.

402trial_exhausted

The free allowance is spent and no card is on file.

402monthly_cap_reached

Your monthly document ceiling was hit.

402canceled

Billing for this account was cancelled.

405method_not_allowed

Only POST. The response carries an Allow header.

409idempotency_key_not_replayable

The key succeeded but its stored response is gone.

413file_too_large

Over 20MB.

415not_a_pdf

The body is not a PDF.

415unsupported_media_type

Neither an application/pdf body nor a multipart file part.

422not_a_bank_statement

Readable, but not a statement.

429too_many_concurrent_requests

More than 4 documents in flight at once.

500parse_failed

Our error.

What is charged#

Only a 200 is billable. Every error is free and none of them count against your monthly cap. X-Billable-Documents is on every response.

What to retry#

Status	Retry	How
`429`	Yes	Four documents are already in flight. Wait a couple of seconds and retry with the same idempotency key.
`500`	Yes	Retry with the same key and exponential backoff. If the same file fails three times, send us the `documentId`.
`402`	After a change	Add a payment method, or ask us to raise the cap. Until then the answer stays the same.
`400`, `401`, `405`, `413`, `415`, `422`	No	The request or the file is the problem. Fix it and send again.
`409`	No	The call already succeeded. Use a new idempotency key only if you want the document parsed and charged again.

Something wrong or missing on this page? [email protected]