Errors
Errors come back in one envelope with a stable code. Branch on the code: messages get reworded, codes do not.
The envelope#
{ "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#
| Status | Retry | How |
|---|---|---|
429 too_many_concurrent_requests | Yes | 4 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_requests | Yes | Test mode only. Wait for the next minute. See Test mode. |
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. |
409 document_processing | After a wait | The document is still being read. Try again once its status is succeeded or failed. |
409 idempotency_key_in_use | Yes | The first call with this key is still opening the file. Retry shortly with the same key to receive its result. |
409 idempotency_key_not_replayable | No | The call already succeeded. Fetch the documentId with GET /api/v1/documents/{id}. |
400, 401, 404, 405, 411, 413, 415, 422 | No | The request or the file is the problem. Fix it and send again. |
Something wrong or missing on this page? [email protected]