Errors: codes, statuses and what to do

Every error is JSON with an error code and a message written to be read. Most arrive inside detail; a few from the edge of the service arrive at the top level. Read error, not the status code alone: several codes share a status.

{"detail": {"error": "file_too_large", "message": "this file is 7.2 MB and the limit is 5 MB"}}

Code	Status	What it means	What to do
`invalid_api_key`	401	The key is unknown, wrong, expired or revoked. The response never says which.	Check the key in your key list; mint a new one if it was revoked or has expired.
`not_available_to_api_keys`	403	This route is for a person signed in, not for a key.	Use a route from the reference.
`missing_capability`	403	This action needs a permission the caller does not have.	Keys may do everything on the reference; this is a signed-in role without that permission.
`account_suspended`	403	The account has been stopped from doing new work.	Write to the operator of this service.
`too_many_requests`	429	The key has used its allowance for now.	Wait the `Retry-After` seconds, then retry. See Limits.
`busy`	503	Every engine slot is in use for a moment.	Wait the `Retry-After` seconds and send the same request again; it did nothing.
`invalid_request`	422	A field is missing or has the wrong shape.	`problems` names each field and what was wrong.
`internal_error`	500	Something failed on our side. Nothing was changed.	Retry; if it repeats, report the time and the route.
`tenant_isolation_violation`	500	The service stopped an answer that would have crossed from one account into another. This is always our fault.	Report the time and the route. Nothing was shown.
`not_found`	404	No such document, job or certificate on this account.	Check the id. Another account's ids are always "not found".
`file_too_large`	413	The upload is over this plan's size limit.	The message names both sizes. See Limits.
`too_many_pages`	422	The document has more pages than this plan allows.	Split it, or see Limits.
`page_too_large`	422	A page is too large to render at the working resolution.	Upload a document with ordinary page sizes.
`not_a_pdf`	422	The file is not a PDF.	Send a PDF.
`unreadable_pdf`	422	The PDF could not be opened.	Re-save it from the program that made it, then upload again.
`no_pages`	422	The PDF has no pages.	Send a document with at least one page.
`password_protected`	422	The document will not open without its password.	Upload again with the multipart field `password`.
`password_incorrect`	422	The password did not open the document.	Check the password.
`password_required`	422	The document needs its password to be read.	Upload again with the multipart field `password`.
`not_protected`	422	A password was sent with a document that has none.	Upload it again without `password`.
`attestation_required`	409	A correction needs a statement of authority first.	Create one with `POST /v1/attestations` and pass its `attestation_id`.
`page_out_of_range`	422	The page index is beyond the document's last page.	Page indexes start at 0.
`stale_or_invalid_confirmation`	409	The document changed after the correction was proposed.	Propose again and apply the new proposal.
`edit_refused`	422	The engine will not make this correction without it showing. `advice` says why and what would change it.	Read `advice`; choose a different region or wording.
`edit_failed`	500	The correction could not be completed for a reason of ours. Nothing was changed.	Retry; if it repeats, report it.
`daily_limit_reached`	429	The free daily correction limit is used. Business keys do not meet this.	`hint` says what would lift it.
`nothing_to_undo`	409	There is no correction to step back from.	Nothing to do.
`nothing_to_redo`	409	No correction has been undone.	Nothing to do.
`no_revision`	404	The document has no corrected version yet.	Apply a correction first.
`no_manifest`	404	The corrected version carries no provenance record.	Apply a correction first.
`nothing_to_export`	409	The document has no corrections to release.	Apply and verify a correction first.
`not_verified`	409	The latest version has not been verified.	Read `GET …/verification`, or apply the correction again.
`verification_hash_mismatch`	409	The document changed after it was verified.	Verify again before exporting.
`verification_failed`	409	Verification did not pass, so the document cannot be released.	Undo the correction the message names.
`diff_outside_expected_region`	409	A correction changed pixels outside the region it declared.	Undo it. This is the failure the check exists to catch.
`payment_required`	402	Nothing on the account pays for this download.	Business accounts do not meet this while the plan runs.
`email_required`	402	This deployment has not started taking payments, and asks for an address first.	Only on a deployment before launch.
`business_plan_required`	402	The route is part of the Business plan and the account is not on it.	See the plans.
`crop_too_large`	422	The crop asked for is over 4 megapixels.	Ask for a smaller region.
`image_too_large`	400	A page of the uploaded file carries an image over 100 megapixels, too large to decode safely.	Rescan or export the document at a lower resolution.
`inspection_budget_spent`	429	The document is not paid for, and today's native pixels inside its corrections are used up. The rest of the page is still served, marked.	Wait until the next UTC day, or pay for the document: once it is paid for there is no limit.
`nothing_to_certify`	409	The document has no corrections to certify.	Apply and verify a correction first.
`correction_not_verified`	409	One of the corrections did not verify, so no certificate can be issued.	Undo it.
`record_does_not_verify`	409	The account's record does not recompute intact, so no certificate can quote it.	Write to the operator of this service.
`certificate_file_deleted`	410	The document the certificate was issued for has been deleted, and the certificate file with it.	The certificate still verifies at `GET /v1/certificates/{id}`.