Skip to content
DocsGuides

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 the request got far enough to allocate one. Quote it in a support question. Some errors carry extra fields: reason and documentId on 409 idempotency_key_not_replayable, pages on a 402, pages and limit on 413 too_many_pages.

A read that fails after an async 202 puts the same code and message on the document instead: status: "failed" and error: { code, message }. See Async reads.

Every code#

400empty_body
The request body was empty.
400missing_file
A multipart request with no part named file.
400invalid_body
The body could not be read.
400invalid_metadata
metadata is not a JSON object of strings, or is over its limits.
400unknown_format
The format query parameter is not json, csv, ofx, qbo or qif.
400format_requires_sync
A format other than json was asked for with async.
400invalid_status
The status filter on a list is not processing, succeeded or failed.
400invalid_starting_after
starting_after on a list names no document or collection of this key's mode.
400invalid_collection
A collection field is missing or out of range.
400test_scenario_on_live_key
X-Test-Scenario was sent with a live key.
400unknown_test_scenario
X-Test-Scenario named a scenario that does not exist.
401missing_key
No Authorization header on the request.
401invalid_key
The key is unknown or has been revoked.
402free_pages_exhausted
The free pages are used up and no payment method is on file.
402not_enough_free_pages
The file has more pages than the free pages left, and no payment method is on file.
402monthly_cap_reached
This file would take the account past its pages for the calendar month.
402canceled
Billing for this account was cancelled.
404document_not_found
No document with that id on this account and mode.
404file_not_kept
The document has no stored file.
404collection_not_found
No collection with that id on this account and mode.
405method_not_allowed
The method is not supported on this path.
409idempotency_key_in_use
A request with this Idempotency-Key is still being processed.
409idempotency_key_not_replayable
The key succeeded but its result can no longer be returned.
409document_processing
The document is still being read.
411length_required
The request has no Content-Length header.
413file_too_large
Over 50MB.
413too_many_pages
Over 60 pages in a synchronous request, or over 500 at all.
415unsupported_media_type
Not a file type the API reads.
422not_a_bank_statement
Readable, but not a statement.
422password_required
The PDF is password-protected.
422incorrect_password
The password sent does not open the PDF.
429too_many_concurrent_requests
More than 4 synchronous reads in flight at once.
429too_many_test_requests
More than 120 test requests in one minute.
500parse_failed
Our error.

What is charged#

Only a successful read is billed, by its pages. Every error is free, a failed read gives its pages back, and none of them count against your monthly cap.

What to retry#

StatusRetryHow
429 too_many_concurrent_requestsYes4 reads are already in flight. Wait a couple of seconds and retry with the same idempotency key, or send with async=true.
429 too_many_test_requestsYesTest mode only. Wait for the next minute. See Test mode.
500YesRetry with the same key and exponential backoff. If the same file fails three times, send us the documentId.
402After a changeAdd a payment method, or ask us to raise the cap. Until then the answer stays the same.
409 document_processingAfter a waitThe document is still being read. Try again once its status is succeeded or failed.
409 idempotency_key_in_useYesThe first call with this key is still opening the file. Retry shortly with the same key to receive its result.
409 idempotency_key_not_replayableNoThe call already succeeded. Fetch the documentId with GET /api/v1/documents/{id}.
400, 401, 404, 405, 411, 413, 415, 422NoThe request or the file is the problem. Fix it and send again.
Something wrong or missing on this page? [email protected]