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 17.2 MB and the limit is 15 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, or another large file is being worked on and this one waited its turn without getting it.	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`	415	The file is not a PDF: judged from its first bytes, never its name.	Send a PDF, or make one of it first with `POST /v1/convert`.
`unknown_tool`	422	The `tool` named is not one of this service's tools. `tools` lists them.	Name one of `tools`, or leave `tool` out for correction.
`tool_mismatch`	422	An upload named one tool in its form and another in its address.	Name the tool once.
`unreadable_pdf`	422	The PDF could not be opened. From the editor's steps: the stored file is damaged past reading, so there is nothing to work on or repair.	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`.
`identity_document_refused`	422	The document was detected as an identity document — a passport, an identity card or a driving licence — which this service does not correct, whatever the reason. Residence permits, diplomas and professional certificates are accepted and never answer this. The file and everything made from it were deleted before this answer was sent. What stays is the record of the refusal, for the audit trail: the file's SHA-256 hash, its size, its page count and page dimensions, and the class with the signals that led to it. `identity_kind` and `confidence` say what was seen and how surely; `reference` is the document id, which stays in the record with the decision. From `POST /v1/documents/{document_id}/classify` only for a caller who could delete the document; anyone else gets a warning on the document instead.	If it is not an identity document, write to the contact the message names, quoting `reference`: the detection is recorded and will be looked at. Nothing needs deleting.
`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. `error` carries the engine's own code in its place when it has one -- `watermark_removal_refused` is the permanent one: the correction would take away part of a watermark or a Bates number, which this service adds and never removes or alters (`how` says how the watermark was found, `share` how much of the selection it is).	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, or will not cover a filled or signed save (`needed`). Business keys do not meet this.	`hint` says what would lift it.
`nothing_to_fill`	422	A fill named no field, and no page for a fillable copy.	Send `fields`, or `pages` with `output` `fillable`.
`nothing_filled`	422	No field was filled, so nothing was saved. `refused` gives each field's reason.	Read `refused`; send a value or a tick for at least one field.
`duplicate_field`	422	One field was named twice in a fill. `field_id` names it.	Send one answer per field.
`field_outside_page`	422	A drawn field's `rect_render` lies outside the page at the `render_dpi` sent.	Check the box and the resolution it was measured at.
`issued_document`	422	The page is an issued document (a certificate, an extract, a report), not a form to complete. `what`, `why` and `do` say so in words.	Ask the issuer for a corrected copy, or upload the blank form.
`xfa_form`	422	The file is an XFA form, which this service does not fill.	Fill it in a reader that runs XFA, or print it to a new PDF and fill that.
`no_fields`	422	A fillable copy was asked for pages with no field found and none drawn.	Draw the fields with `rect_render` and `kind`.
`fill_refused`	422	The engine declined the whole fill. `code` names why. Nothing was changed.	Read `code`; fill fewer fields at once, or report it.
`fill_failed`	500	The form could not be filled for a reason of ours. Nothing was changed.	Retry; if it repeats, report the time and the route.
`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.
`download_first`	409	Protect or unlock was given a document that has changed since it was uploaded.	Download it through the export gate, then send the file.
`file_missing`	422	Protect or unlock was sent neither a file nor a document.	Send a PDF, or name a document here nothing has been done to.
`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. Also 422 from `POST /v1/documents/{document_id}/overlays`: an overlay image is over 2 MB decoded (`bytes` and `limit`).	Rescan or export the document at a lower resolution; save an overlay image smaller.
`ink_edit_refused`	422	An overlay would cover the page's own ink: an opaque box, an opaque text box or an opaque image over words, a rule, a filled form field or an annotation already there. Several washes, or washes and a flatten, that together leave a mark of the page's own ink less than half its contrast against the paper -- fading it, or blacking it out -- are refused the same way (`evidence.how`: `covers`, `erases` or `buries`). The editor never fakes a change to the page with a box and new text. `advice` points at the routes that do it honestly.	Change the words with a correction (`POST /v1/documents/{document_id}/edits`), which changes them in place and is checked; remove something for good with a redaction; or make the overlay transparent, which is an annotation.
`overlay_invisible`	422	An overlay would change nothing that can be seen where it is laid: paper-coloured markup on paper, for example a white underline. Nothing was changed.	Choose a colour that shows on the page.
`off_page`	422	An overlay's box or points, or a crop box, lies outside the page at the `render_dpi` sent; or a crop's margins leave nothing of the page. `page` names it.	Check the box and the resolution it was measured at, or ask for smaller margins.
`too_many_overlays`	422	More overlays in one step than it takes (`count` and `limit`).	Send them in batches of at most `limit`.
`image_unreadable`	422	An overlay's `image_data` is not valid base64, or not a PNG or a JPEG.	Send a PNG or a JPEG in base64.
`text_too_long`	422	A text box or a note holds more characters than one may (`limit`).	Shorten it, or add a second box.
`font_cannot_draw`	422	The text holds characters the chosen face (`sans`, `serif` or `mono`, the standard faces) cannot draw; `characters` lists them.	Leave those characters out, or write them in Latin letters.
`signed_document`	422	The document carries a digital signature, which any change made here would break: an overlay, a crop, a flatten or a redaction.	Work on a copy that has not been signed, or ask the signer for one; signing it again afterwards is for the signer.
`protected_feature`	422	The step would cover or remove a watermark, a Bates number, a signature, a seal or another security feature, which this service never hides or removes, whoever asks; `feature` names it.	Place the overlay or the region where it is not. If the document should not carry it, ask whoever issued it for a copy without it.
`nothing_to_flatten`	422	A flatten was asked of a document with no annotation and no form field to bake in.	Nothing to do.
`nothing_to_uncrop`	422	A crop was asked to be put back on pages the record never cropped.	Nothing to do.
`nothing_to_repair`	422	A repair was asked of a file that opened cleanly, so there was nothing to rebuild.	Nothing to do.
`editor_failed`	500	The step did not hold when it was read back -- something beneath an overlay or a crop changed -- so nothing was made. This is always our fault.	Report the time and the route. Your document is as it was.
`unknown_overlay`	422	An overlay to remove is not on any page: `names` lists those not found.	Name the overlays as the step that added them recorded them (`ceco-…`).
`bad_request`	422	A value the editor cannot use as given: a stroke too wide for the page, a text size out of range, a text box or a note with no words. `message` says which.	Adjust the request.
`query_too_short`	422	A redaction find's `query` holds fewer than three characters, spaces not counted. `advice` says so.	Search for the word or phrase, not a letter or two.
`pattern_unknown`	422	A redaction find's `pattern` is not one the engine knows.	One of `email`, `phone`, `iban`, `card`, `date` or `number`; or send `query` or `regex`.
`regex_invalid`	422	A redaction find's `regex` does not compile, is over 200 characters, or repeats a group that itself repeats or branches. `advice` says which.	Simplify the expression, or search for the words with `query`.
`ocr_unavailable`	422	A redaction find was asked to read a scanned page, and the engine has no text recogniser, or not the language. The find answers with the scanned pages counted in `scanned_pages_unread` instead wherever it can tell beforehand.	Draw the regions on the scanned pages by hand.
`redaction_invalid`	422	A redaction that cannot be made as asked: a region with no width or height, or a `label` mark with no label. `message` says which.	Drag over what should go, or tick a match; give the label its words.
`region_off_page`	422	A region lies wholly outside its page (`page_index`). The part of a region past the page's edge is not redacted; a region with nothing on the page is refused.	Draw the region on the page.
`too_many_regions`	422	One redaction takes at most 200 places, counted after a match sent both as regions and by id is counted once. `regions` and `limit` give both numbers.	Redact in parts.
`label_too_long`	422	A `label` mark's label is over 40 characters, its spaces run together. `length` and `limit` give both.	Shorten the label.
`label_cannot_draw`	422	The label holds a character the mark's typeface (standard Helvetica) cannot draw, or a control character.	Use Latin letters in the label, or choose a black or white mark.
`match_stale`	409	`match_ids` name matches not found on the document as it now stands -- it changed since the find (a correction, an undo, a redaction), or the find was answered by another server -- or a match whose boxes the regions do not all carry. `stale` counts them. Nothing was changed.	Search again, tick the matches again, and send the new ids with their boxes.
`nothing_redacted`	422	Every region was declined, so the document is unchanged. `refused` lists each, with its `code`, `feature` and `advice`.	Draw the regions away from what is protected.
`removal_not_verified`	422	What was in the regions could not be shown to be gone from every layer of the file, so nothing was changed. `checks` names each check (`text_layer`, `images`, `raw_bytes`, `ocr`, `render_boxes_blank`, `text_in_regions`), `failed` the ones that found something, and `characters_left` how many characters of the text layer still stood in a region.	A larger region may cover what was left; read a scanned page first. Report it if it repeats.
`removal_failed`	422	Text a region chose could not be taken out of the file, even on a second pass at each character left, so nothing was saved. `page` says where.	Try a slightly larger region. If it repeats, report it: the engine marks it worth reporting.
`too_many_pages_to_redact`	422	One redaction changes at most 10 pages, and this one names places on more. `pages` and `limit` give both numbers. Nothing was changed or charged.	Redact the document in parts, ten pages at a time, or split it first.
`too_many_scanned_pages`	422	A redaction find would read more scanned pages afresh than one find reads, 5: `pages` and `limit` give both numbers. A page read once is remembered, and not counted again.	Find on fewer pages at a time with `pages` (indexes 0 to 4, then the next five); a find over every page then reads only what is new.
`redaction_failed`	500	The content could not be removed without changing something else on a page (`outside_pixels` counts the pixels), or something failed on our side, so nothing was made. This is always our fault.	Report the time and the route. Your document is as it was.
`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.
`page_op_out_of_range`	422	A page number or range in a page operation is outside the document, or is not a page number. `page` and `page_count` say which and how many.	Pages are counted from one: `1-3, 5, 8-`.
`page_op_invalid`	422	A page operation that cannot be carried out as asked: nothing left after a removal, a new order that does not name every page once, a turn that is not a multiple of 90, a split with no way or two. `message` says which.	Adjust the request.
`page_op_part_too_large`	422	Splitting by size: one page on its own is larger than `max_mb`. `page` and `bytes` say which and how large.	Ask for a larger size, or split by ranges.
`page_op_memory_ceiling`	422	The documents are too large to work on together. `input_bytes`, `needed_bytes` and `ceiling_bytes` give the arithmetic.	Merge fewer at a time, then merge the results.
`source_not_verified`	409	A document's latest correction did not verify, so its pages cannot be moved into another file.	Undo that correction first.
`page_operation_failed`	500	The pages could not be carried over unchanged, so nothing was made. This is always our fault.	Report the time and the route. Your documents are as they were.
`marks_invalid`	422	A watermark, page number, header, footer or Bates number that cannot be drawn as asked: no text, an opacity, size, rotation or margin out of range, a placeholder other than `{page}` and `{pages}`, two lines in one place, an image watermark more than half opaque. `message` says which.	Adjust the request.
`marks_glyph_missing`	422	The text holds characters the chosen face cannot draw; `characters` lists them. The six standard faces draw Latin script (Western European languages and Albanian included).	Leave those characters out, or write them in Latin letters.
`marks_image_unreadable`	422	The watermark image is not valid base64, not a PNG or a JPEG, over 10 MB or over 25 megapixels.	Send a PNG or a JPEG.
`marks_would_cover`	422	A page number, header, footer or Bates number would land on something already on a page -- a word, a line, a form field -- and hide it. `page` and `position` say where.	Another position, a larger margin or a smaller size, or leave that page out.
`marks_do_not_fit`	422	The mark is larger than the page leaves inside its margins (`mark` and `room`, in points), or the Bates numbers would run past `digits`.	A smaller size or margin, or more digits.
`marks_failed`	500	A marked page changed outside its marks when it was read back, so nothing was made. This is always our fault.	Report the time and the route. Your documents are as they were.
`protect_invalid`	422	A protection that cannot be set as asked: no password; restrictions with no owner's password, or with the opening password as the owner's; an owner's password with nothing restricted; a password over 40 characters, or holding a character PDF readers read differently. `message` says which.	Adjust the passwords or the permissions.
`protect_not_pdf`	422	The file cannot be read as a PDF, or has no pages.	Check it opens in a PDF reader.
`protect_password_needed`	422	The file is protected and no password was given for it. This tool never tries to find one.	Send `password`.
`protect_password_wrong`	422	The password given does not open the file. It was tried once; nothing else was tried.	Check it and try again. `/v1/unlock` allows ten tries in ten minutes.
`protect_owner_password_needed`	422	The file opens, but its owner restricted it, and lifting or replacing the restrictions needs the owner's password. `permissions_withheld` lists them.	Send the owner's password.
`protect_not_protected`	422	Asked to unlock a file that has no password and no restrictions.	Use it as it is.
`protect_failed`	500	The protected file, read back, did not hold what was asked, so it was not returned. This is always our fault.	Report the time. Nothing was kept.
`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}`.
`compress_too_large`	413	The file sent to be compressed is over the compress ceiling, 100 MB for every plan unless the deployment sets another. `size_mb` and `limit_mb` give both numbers; a file refused part way through the upload says "over", because reading on to measure it is the thing being avoided.	Split it first, or compress it in two halves.
`compress_expired`	410	The compression's options are gone: they are kept for an hour, or until one of them is made a document, or until they are deleted. `status` says which (`expired` or `done`).	Send the file again.
`compare_too_many_pages`	422	A comparison's answer, in `refusal`: one of the documents has more pages than a comparison may hold on this plan. `file` (`before` or `after`), `pages` and `limit_pages` say which and how many.	Compare the part that changed: split both at the same pages, and compare the parts.
`compare_not_ready`	409	The comparison has not finished (`status` says where it is), so there is no report or CSV yet.	Poll `GET /v1/compare/{job_id}` until `status` is `done`.
`compare_report_paid`	402	A comparison is shown to everybody; its report and its CSV come with a subscription, or a pack bought in the last thirty days.	Buy a plan, then ask again. The comparison is kept until you delete it or either document is deleted.
`compress_busy`	409	A step on this compression is already running (a size, a choice or a split), or it is still working when asked to delete.	Poll `GET /v1/compress/{job_id}` until `status` is `ready`, then ask again.
`compress_not_ready`	409	The options are still being made, or making them failed (`status` says which).	Wait for `status` to be `ready`; after `failed`, send the file again.
`compress_no_such_option`	422	The option chosen is not one this compression offers: `options` lists the numbers it does (5 only once a size has been asked for).	Choose one of `options`.
`compress_failed`	200	In `choice_refusal` of `GET /v1/compress/{job_id}`: a step could not be finished after three attempts, and nothing was made or charged. The options are as they were. This is always our fault.	Try again, or choose another option.
`compress_unverified`	200	In `choice_refusal`: the file chosen did not pass its own reading check when it was written, so no document was made from it. `worst_ssim` and `floor` give the numbers. This is always our fault.	Choose another option, and report the time.
`ocr_language_unknown`	422	The language named in `lang` is not one this server reads, or, in a reading's `refusal`, the pages are written in a script no language it has can read. `lang` says what was asked.	Name one from `GET /v1/ocr/languages`, or ask for `auto`.
`ocr_not_ready`	409	The reading has not finished (`status` says where it is), or it made nothing, so there is no text to download yet.	Poll `GET /v1/ocr/{job_id}` until `status` is `done`.
`ocr_not_tabular`	422	Asked for `table.csv` of a reading in which no page is clearly laid out as a table, so there are no rows to give; the same refusal is in `csv_refusal` of the reading. The text and the laid-out text still have every word kept.	Download `text.txt` or `layout.txt`.
`ocr_unreadable`	200	In `refusal` of `GET /v1/ocr/{job_id}`: nothing on any page could be read with enough confidence to be given words, so nothing was made, rather than a searchable copy that finds the wrong places. `pages` says each page's state.	Scan it again sharper, at 300 dpi or more, or name its language.
`ocr_nothing_to_read`	200	In `refusal` (or `pdf_refusal` when the text was still made): no page is a scan; each has its own text already, or nothing to read.	Search and copy from it as it is; its text can still be had with `text` in `outputs`.
`ocr_too_many_pages`	200	In `refusal`: the document has more pages than a reading may hold on this plan. `pages` and `limit_pages` say how many.	Split it, and read the parts.
`ocr_failed`	200	In `refusal`: the text layer could not be added without changing something else in the file, so nothing was made. This is always our fault.	Report the time. Your document is as it was.
`provider_unavailable`	200	In `refusal`: this server has no reading engine installed, or not the language asked, so it cannot read scans. `GET /v1/ocr/languages` says `available: false`.	Write to the operator of this service.
`convert_not_ready`	409	The PDF export has not finished, failed or was refused, so no ZIP is available.	Poll `GET /v1/convert-from-pdf/{job_id}` until `status` is `done`; read `refusal` before choosing another format or request.
`convert_invalid`	422	A conversion that cannot be made as asked: no file sent, more than 50 files (`files` and `limit_files`), or an option out of range (`option` names it). The same code in a conversion's `refusal`, for what the converter itself was asked.	Adjust the request.
`convert_too_large`	413	The files sent come to more than 32 MB together, which is all one request may carry: `bytes`, `limit_bytes` and `files` say how much and how many. In a conversion's `refusal` (with 200): a picture larger than this server opens -- 100 megapixels when its own compressed data is kept, fewer when it has to be decoded first (`limit_megapixels` says how many) -- an Office file too large for the converter, a ZIP listing more parts than any document does, or a PDF that would have more pages than a conversion makes or this plan allows (`measure` is `pages`, and `limit` this plan's pages: the file is stopped there, before the rest of it is made); the refusal carries the limit, and the figure wherever one was counted. PDF exports also refuse input over 32 MiB, more than 50 pages, an image canvas beyond the memory budget, or output over 64 MiB; the message names the limit.	Convert fewer files at a time, then merge the PDFs; save a very large picture smaller.
`convert_unsupported`	200	In `refusal`: an input kind cannot be converted into PDF, or a PDF export cannot honestly preserve the requested fidelity. Examples include annotations or form appearances the renderer would omit, a complex page outside Word’s limits, or unavailable/failed PDF/A validation.	For conversion into PDF, send a kind `POST /v1/convert` accepts. For exports, read the refusal and choose another format or export from the original application.
`convert_unreadable`	200	In `refusal`: a file is a kind this converts but cannot be read as one -- damaged, cut short, or text in no encoding it can read. With 422, from `POST /v1/convert` itself: a file is empty (`file` says which, counted from one; `reason` is `empty`).	Save it again from the program that made it; save text as UTF-8.
`convert_characters_missing`	200	In `refusal`: the text uses characters none of the converter's fonts can draw; `characters` lists them. Nothing is made rather than a page with empty boxes where they were.	Leave those characters out, or make the PDF in the program the text was written in.
`convert_runaway_layout`	200	In `refusal`: laying out a text file or a web page did not settle -- it kept making pages past the limit, or something in it cannot be fitted on a page.	Shorten it, or convert it in parts.
`convert_password_needed`	200	In `refusal`: an Office file is locked with a password. The converter cannot take one, and does not try to get past it.	Save a copy without the password in the program that made it, and send that.
`convert_timed_out`	200	In `refusal`: the conversion took longer than it may (`seconds`), and was stopped; nothing was kept. An Office file this slow is usually very long or full of pictures.	Convert it in parts.
`convert_office_unavailable`	200	In `refusal`: this server cannot convert Office files -- no converter is set up for it, or the converter did not answer. Photos, text and web pages still convert.	Save it as a PDF in the program that made it, or write to the operator of this service.
`convert_failed`	200	In `refusal`: the PDF could not be made and checked, so nothing was kept. This is always our fault.	Send the files again; if it happens again, report the time.

Refusals inside a compression's answer

A compression that cannot give what was asked answers with the reason, in refusal, under.refusal or choice_refusal of GET /v1/compress/{job_id}, not with an error status: the request was fine, and the file is the reason. Each carries error, message, its numbers and advice (what, why, do) written for the person holding the file, and none of them is retried.

compress_nothing_to_gain (refusal): no setting saves a tenth of the file. original_bytes, best_bytes and budget (bytes of page images, fonts, content and everything else) say where its bytes are.
compress_below_floor (refusal): every setting that would save a tenth makes some page harder to read than the floor allows. worst_page, worst_ssim and floor.
compress_over_limit (under.refusal): the smallest file that stays readable is over the size asked for. smallest_bytes, max_bytes, and split_offer: true — POST /v1/compress/{job_id}/split makes parts each under it.
compress_unreadable (refusal): the engine could not read a file the door let in.
page_op_part_too_large, page_op_memory_ceiling, too_many_pages (choice_refusal, after a split): as for page operations above.
identity_document_refused (choice_refusal): the file made was detected as an identity document and deleted, with the options; status is failed.

What a reading says instead of refusing

A reading (GET /v1/ocr/{job_id}) is refused only when nothing at all could be made. Short of that, each page says what became of it in pages[].state, and the answer is done:

read: the page was read with confidence and its words written; the few read too unsurely, if any, were still left out (words_withheld).
partial: some words were read with too little confidence and left out of the text layer and the text, rather than guessed; words_withheld counts them.
unreadable: nothing on the page could be read with confidence, so it was given no words at all, rather than wrong ones.
skipped: the page has its own text already (skipped_because is has_text, or has_text_layer for a searchable layer it already carries), or nothing to read (blank, empty, drawing, or not_a_scan for pictures that do not cover it), so it was given no layer; any text of its own is in the text outputs, quoted as it stands rather than read. Its source is then text_layer, and its note says the words are the file's own -- or another program's searchable text -- and were not read or checked here: a poor layer a scanner's software wrote comes out as poor as it is.

A refusal of one output leaves the others: pdf_refusal (ocr_nothing_to_read) when every page already had text and only the text was made, and csv_refusal (ocr_not_tabular) when no page is a table.

Regions declined during a redaction

A redaction declines a region rather than the whole request when the region holds something this service never removes, and redacts the rest. Each declined region is listed in refused of the answer to POST /v1/documents/{document_id}/redactions, with its page_index, its box_render and render_dpi as they were sent, its code (protected_feature), the feature found -- watermark, bates, signature, seal, microprint or guilloche -- and advice (what, why, do). When every region is declined the request is refused whole: protected_feature, or nothing_redacted, with nothing changed and nothing charged.

Fields refused during filling or signing

The refused list explains each field separately, including what, why and do. Other fields can still succeed. If none succeeds, the request returns 422 nothing_filled and makes no revision or allowance charge.

signature_not_owned: the person has not confirmed that the supplied mark belongs to them. Supply and confirm only your own mark.
signature_existing: existing ink, a filled form field, an annotation, or a file marked as digitally signed makes the placement unsafe. Choose a blank area or a fresh unsigned copy; ownership is never inferred from pixels.
signature_invalid: the supplied mark, canvas proportions or page rectangle is invalid. Use a supported typed name, pointer trace, PNG or JPEG.
signature_empty: the supplied image contains no visible ink.
signature_glyph_missing: standard italic cannot draw every typed letter. Draw or upload your own mark instead.

Last updated 12 November 2026