Errors
The error shape, every type and code, and what to do about each.
On this page
Every ReceViz error, from the API or the console, has one shape and a machine-readable code. Branch on type, look up code, log message, and quote request_id when you ask for help.
The error body#
{
"error": {
"type": "permission_error",
"code": "missing_capability",
"message": "VERIFIED mode needs the documents.verify capability.",
"details": {
"missing": [
"documents.verify"
]
},
"request_id": "rv_req_8fK2aQ0zT3mN1pL5vB7xY9",
"doc_url": "https://receviz.theaccounthouse.com/docs/errors#missing_capability"
}
}| Field | What it holds |
|---|---|
type | The broad class, one of the types below. Branch on it. |
code | The precise reason. Look it up on this page. |
message | A sentence for the developer reading a log, never for the person using your app. |
param | The parameter at fault, when there is one: file, options.tiling, restrictions.allowed_ips. |
details | More, when it helps: missing capabilities, the problems in a definition, the parameters that failed validation. |
request_id | The request's id, the same as the X-Request-Id header on every response, errors included. |
doc_url | A link to the code's entry on this page. |
An error never repeats document content or the values you sent: a parameter that failed validation is named, not echoed. A 401 also carries WWW-Authenticate: Bearer realm="receviz", and a 429 carries Retry-After.
Types#
| type | Status | Meaning | What to do |
|---|---|---|---|
invalid_request_error | 400 | The request is wrong: a missing or malformed parameter, or a file ReceViz cannot accept. | Fix what param and message point at. Retrying the same request gives the same answer. |
authentication_error | 401 | No credential, or one that is unknown, revoked or expired. | Check the key or token. For an expired client token, get a new one from your server. |
permission_error | 403 | The credential is valid but may not do this. | Grant the capability, loosen the restriction, or use the right kind of key. Retrying does not help. |
not_found_error | 404 | The object does not exist for this application. | Check the id or key. Objects are only visible to the application or organization they belong to. |
conflict_error | 409 | The request conflicts with the state of something: an idempotency key already used, a draft not yet published. | Read the message: it says which state is in the way. |
rate_limit_error | 429 | Too many requests this minute, or a monthly quota used up. | Wait the number of seconds in the Retry-After header, then retry. |
processing_error | 504 | The document could not be read within the request's time. | Send the document again with async=true. |
api_error | 500 | Something failed on ReceViz's side. | Retry with a pause. If it keeps failing, quote the request id when you ask for help. |
service_unavailable_error | 503 | ReceViz, or the part of it this request needs, is unavailable right now. | Retry later. |
A code of the form http_<status> comes from the HTTP layer in front of ReceViz rather than from ReceViz itself; the status says what happened.
What to retry#
- Retry a
429afterRetry-Afterseconds, and a500,503or a lost connection after a pause that grows with each attempt. - Do not retry unchanged a
400,401,403,404or409: the same request gets the same answer. - Retry differently a
504 processing_timeout: send the document again withasync=true. - Send an
Idempotency-Keywith everyPOST /v1/extractions, so that a retry after a lost response returns the first extraction instead of making a second. See Retry safely.
Credentials#
Returned before anything else is looked at, on any endpoint.
missing_credentials401authentication_error
The request carried no credential.
What to do: Send the key or token as Authorization: Bearer <credential>.
invalid_credentials401authentication_error
The credential does not start with a ReceViz prefix (rv_live_, rv_test_, rv_pk_live_, rv_pk_test_ or rv_ct_).
What to do: Check that the whole key was copied and that nothing else is in the header.
invalid_api_key401authentication_error
No key matches, or its application or organization no longer exists.
What to do: Check the key for missing characters. Create a new key in the console if it was lost.
api_key_revoked401authentication_error
The key was revoked. A client token answers this too when the key that minted it was revoked.
What to do: Use another active key, and mint new client tokens from it.
api_key_expired401authentication_error
The key reached its expiry date, or the grace period of a rotated key ended.
What to do: Switch to the key that replaced it, or create a new one.
invalid_token401authentication_error
A client token is malformed, its signature does not check out, or it no longer matches its key's application.
What to do: Mint a new token. Tokens must be passed on exactly as ReceViz issued them.
token_expired401authentication_error
A client token is past its expiry.
What to do: Ask your server for a new token (the Web, iOS and Android SDKs renew once on their own).
publishable_key_not_allowed403permission_error
A publishable key was used on an endpoint other than POST /v1/client-sessions.
What to do: Exchange the publishable key for a client token first, and call the API with the token.
publishable_key_required403permission_error
POST /v1/client-sessions was called with a secret key or a client token.
What to do: Open client sessions with a publishable key. With a secret key, use POST /v1/client-tokens instead.
secret_key_required403permission_error
POST /v1/client-tokens or POST /v1/document-types was called without a secret key.
What to do: Call these from your server with a secret key.
ip_not_allowed403permission_error
The key has an IP allow-list and the request came from an address outside it.
What to do: Call from an allowed address, or add the address or range to the key's restrictions.
origin_not_allowed403permission_error
The publishable key is restricted to web origins or app bundle identifiers, and the request matched neither.
What to do: Add the page's origin (scheme://host[:port]) or the app's bundle identifier to the key.
tenant_suspended403permission_error
ReceViz has suspended the organization's access. Every key of the organization is refused.
What to do: The console shows the suspension. Contact ReceViz to have it lifted.
tenant_closed403permission_error
The organization is scheduled for deletion. Every key of the organization is refused, and the console is read-only.
What to do: An owner can cancel the deletion in the console, under Data and privacy, until the date it shows.
application_disabled403permission_error
The key's application is disabled or archived.
What to do: Enable the application in the console. Archiving revokes an application's keys, so an archived one needs a new application.
Capabilities and document types#
missing_capability403permission_error
The request needs a capability the credential does not hold. details.missing lists which.
What to do: A capability must be granted to the organization, enabled on the application and held by the key (and by the client token).
scope_not_granted403permission_error
A client token was asked for capabilities its key cannot pass on (details.not_granted), or a key or application for more than its application or organization has.
What to do: Ask only for capabilities the key holds and a public client may hold. Server-only capabilities never reach a client token.
verification_disabled403permission_error
VERIFIED mode was asked for, but the data policy keeps document text away from language models (llm: disabled).
What to do: Use STANDARD mode, or allow language models in the organization's and the application's data policy.
custom_document_types_not_allowed403permission_error
The document type is the organization's own and the credential lacks schemas.execute. Types created from a built-in template do not need it.
What to do: Grant schemas.execute, or extract with a type created from a template.
document_type_not_assigned403permission_error
The application has a list of document types and this one is not on it.
What to do: Assign the document type to the application in the console, or use one that is assigned.
document_type_not_allowed403permission_error
The client token was minted for other document types.
What to do: Mint a token whose document_types include this one, or none (all the application's types).
document_type_required400invalid_request_error
No document_type was sent and the application has no default (a default assignment, or exactly one assigned type).
What to do: Send document_type, or set a default document type on the application.
document_type_not_found404not_found_error
No active document type with this key for the application. POST /v1/client-tokens and /v1/client-sessions answer it as a 400, with param document_types, for a type the application cannot use.
What to do: Check the key with GET /v1/document-types.
document_type_unpublished409conflict_error
The document type has only a draft; extraction always runs against a published version.
What to do: Publish the draft in the console.
version_not_found404not_found_error
The document type has no published version with this number.
What to do: List the versions in the console, or leave schema_version out to use the pinned or latest one.
schema_not_found404not_found_error
No published version with this schema id exists in the organization.
What to do: Use the schema_id an extraction returned.
Request parameters#
invalid_parameters400invalid_request_error
A parameter is missing or has the wrong type. details.errors lists each as {param, message}; the values you sent are never repeated back.
What to do: Correct the parameters named in details.errors.
invalid_json400invalid_request_error
options, metadata or client_ocr is not valid JSON. param says which.
What to do: Send the form field as a JSON string, e.g. options={"tiling":"off"}.
invalid_options400invalid_request_error
options is valid JSON but not an object.
What to do: Send an object: {"include_ocr": "text"}.
invalid_option400invalid_request_error
One option has a value it cannot take. param names it, e.g. options.tiling.
What to do: Use one of the values listed for that option in the Extractions guide.
invalid_mode400invalid_request_error
mode is not fast, standard or verified.
What to do: Send one of the three, or leave it out for the application's default.
invalid_metadata400invalid_request_error
metadata is not a JSON object of strings, numbers, booleans or nulls, or is larger than 2048 bytes.
What to do: Keep metadata flat and small: your own ids, not document content.
invalid_client_ocr400invalid_request_error
client_ocr is not {width, height, lines} (or {pages: [...]}), or has no lines of text. Text that is not JSON at all is invalid_json.
What to do: Send the device's lines with coordinates from 0 to 1, origin top-left.
no_document400invalid_request_error
Neither a file nor client_ocr was sent.
What to do: Send the document as file, or the text the device read as client_ocr.
invalid_idempotency_key400invalid_request_error
The Idempotency-Key header is longer than 128 characters.
What to do: Use a shorter key, such as a UUID.
idempotency_key_reused409conflict_error
The same Idempotency-Key was sent with a different request by the same key in the last 24 hours.
What to do: Use one idempotency key per distinct request; reuse it only to retry that request.
extraction_not_found404not_found_error
No extraction with this id belongs to the calling application. Extractions are visible only to the application that created them.
What to do: Use the id the extraction was created with, and a key of the same application.
invalid_ttl400invalid_request_error
ttl_seconds for a client token is outside 60 to 3600.
What to do: Ask for a lifetime between one minute and one hour.
no_scopes400invalid_request_error
The client token (or key) would hold no capability at all.
What to do: Ask for at least one capability the key holds and a public client may hold.
invalid_key400invalid_request_error
A document type key is not 2 to 64 characters of a-z, 0-9 and _, starting with a letter.
What to do: Use a key like payment_receipt.
key_taken409conflict_error
The organization already has a document type with this key.
What to do: Choose another key, or publish a new version of the existing type.
unknown_template400invalid_request_error
template is not one of the built-in templates.
What to do: Use payment_receipt, retail_receipt or invoice.
invalid_definition400invalid_request_error
The definition breaks the definition language. details.problems lists every problem at once, each as {path, message}.
What to do: Fix each problem at its path, e.g. fields[2].type.
too_many_document_types409conflict_error
The organization has as many active document types as it may have (50 unless ReceViz set another limit).
What to do: Archive a document type you no longer use.
Documents#
The file is judged by its bytes, never by its name or declared type.
empty_file400invalid_request_error
The file has no bytes.
What to do: Check that the upload read the file before sending it.
file_too_large400invalid_request_error
The file is larger than the limit: 20 MB, or a lower limit set for the organization.
What to do: Send a smaller file. The Web SDK's normalizeImage scales a photo down before upload.
unsupported_media_type400invalid_request_error
The bytes are not JPEG, PNG, WebP, TIFF, HEIC/HEIF or PDF. AVIF is refused with this code too.
What to do: Convert the document to JPEG, PNG or PDF.
heic_unsupported400invalid_request_error
The file is HEIC or HEIF and this ReceViz deployment cannot decode it.
What to do: Send JPEG or PNG instead.
image_too_large400invalid_request_error
The image is more than 14,000 pixels on a side or 60 megapixels, or decompresses to more pixels than that.
What to do: Scale the image down. The Web SDK sends photos at 2,400 pixels on the long side (3,264 for a long receipt).
unreadable_image400invalid_request_error
The image is damaged, truncated or cannot be decoded.
What to do: Send the original file again, not a partial upload.
unreadable_pdf400invalid_request_error
The PDF cannot be parsed, or one of its pages cannot be rendered.
What to do: Re-export the PDF, or send the pages as images.
pdf_encrypted400invalid_request_error
The PDF is password-protected.
What to do: Send it without a password.
too_many_pages400invalid_request_error
A PDF or multi-page TIFF has more than 30 pages, or more than a lower limit set for the organization.
What to do: Split the document and send the parts separately.
processing_timeout504processing_error
Reading the document took longer than the synchronous deadline (90 seconds). An asynchronous extraction that stays stuck fails with this code after three attempts.
What to do: Send large or slow documents with async=true and poll, or subscribe to extraction.completed.
Rate limits and quotas#
rate_limited429rate_limit_error
The credential sent more requests this minute than its limit. The console answers this too for its own limits.
What to do: Wait Retry-After seconds. X-RateLimit-Remaining tells you how close you are before it happens.
quota_exceeded429rate_limit_error
The organization has used its documents for the calendar month (UTC).
What to do: Retry-After counts down to the start of next month. Ask ReceViz to change the quota.
key_quota_exceeded429rate_limit_error
This key has used its own monthly quota (a restriction set on the key).
What to do: Raise or remove the key's monthly quota in the console, or use another key.
Service#
internal_error500api_error
Something unexpected failed while handling the request. It is logged on ReceViz's side; no stack trace is ever returned.
What to do: Retry. If it keeps happening, quote the request id.
receviz_disabled503service_unavailable_error
The public API is switched off, for example during maintenance. The console keeps working.
What to do: Retry later.
Console errors#
The console answers with the same body. These codes come from managing keys, webhooks, document types and the organization.
Keys#
invalid_kind400invalid_request_error
A key's kind is neither secret nor publishable.
What to do: Choose one of the two.
unknown_scope400invalid_request_error
A capability code does not exist.
What to do: Use the codes listed in the Capabilities guide.
scope_not_public400invalid_request_error
A publishable key was given a server-only capability.
What to do: Leave schemas.write, webhooks.receive, usage.read and client_tokens.create to secret keys.
too_many_credentials409conflict_error
The application already has 25 active keys.
What to do: Revoke a key you no longer use.
invalid_expiry400invalid_request_error
expires_in_days is outside 1 to 3650.
What to do: Choose an expiry within ten years, or none.
credential_inactive409conflict_error
Only an active key can be rotated; this one is revoked or expired.
What to do: Create a new key instead.
invalid_grace400invalid_request_error
A rotation's grace period is outside 0 to 168 hours.
What to do: Choose up to seven days; 0 revokes the old key at once.
credential_not_found404not_found_error
No such key in this application.
What to do: Refresh the list of keys.
tenant_inactive403permission_error
Keys cannot be issued while the organization is not active.
What to do: Contact ReceViz about the organization's status.
application_inactive403permission_error
Keys cannot be issued for an application that is not active.
What to do: Enable the application first.
invalid_origin400invalid_request_error
An allowed origin is not scheme://host[:port].
What to do: Use e.g. https://app.example.com or https://*.example.com, without a path.
invalid_bundle_id400invalid_request_error
An allowed bundle identifier is not in reverse-domain form.
What to do: Use e.g. com.example.app.
invalid_ip400invalid_request_error
An allowed IP is not an address or a CIDR range.
What to do: Use e.g. 203.0.113.7 or 203.0.113.0/24.
too_many_restrictions400invalid_request_error
More than 50 entries in one restriction list.
What to do: Use wildcard origins or CIDR ranges to cover more with fewer entries.
restriction_not_applicable400invalid_request_error
Origins or bundle identifiers were set on a secret key.
What to do: Restrict a secret key by IP instead; origins and bundle identifiers are for publishable keys.
invalid_rate_limit400invalid_request_error
A key's rate limit is not a whole number from 1 to 100000.
What to do: Enter requests per minute as a whole number.
invalid_quota400invalid_request_error
A key's monthly quota is not a whole number of at least 1.
What to do: Enter documents per month, or leave it empty for no quota.
Webhooks#
invalid_webhook_url400invalid_request_error
The URL is not https, carries a user name or password, or is not a valid URL.
What to do: Use a plain https:// URL.
webhook_url_not_public400invalid_request_error
The host is local (localhost, .local, .internal) or resolves to a private, loopback, link-local or reserved address.
What to do: Point the webhook at an address reachable from the public internet.
webhook_url_unresolvable400invalid_request_error
The host name does not resolve.
What to do: Check the DNS name.
unknown_event400invalid_request_error
An event name is not extraction.completed, extraction.failed or verification.completed.
What to do: Subscribe to those, or to none for all three.
too_many_endpoints409conflict_error
The application already has 5 webhook endpoints.
What to do: Delete one, or send several events to one endpoint.
webhook_not_found404not_found_error
No such endpoint in this application.
What to do: Refresh the list of endpoints.
encryption_unconfigured503service_unavailable_error
The deployment cannot encrypt webhook signing secrets, so it cannot store one.
What to do: An operator has to configure the encryption key; report it to ReceViz.
Document types#
document_type_archived409conflict_error
An archived document type cannot be edited.
What to do: Create a new document type.
nothing_changed409conflict_error
The draft is the same as the latest published version.
What to do: Change the draft, or keep the version you have.
breaking_change409conflict_error
The draft changes the schema in a way that can break integrations. details.changes lists the breaking changes.
What to do: Publish it deliberately as a new version (acknowledge the breaking change). Applications pinned to earlier versions keep them.
invalid_version400invalid_request_error
An application was pinned to a version the document type does not have.
What to do: Pin a published version, or none to follow the latest.
Applications, members and access#
invalid_environment400invalid_request_error
An application's environment is not development, test or production.
What to do: Choose one of the three. Production applications issue live keys.
too_many_applications409conflict_error
The organization has as many applications as it may (20 unless ReceViz set another limit).
What to do: Archive an application you no longer use.
invalid_setting400invalid_request_error
An application setting has a value it cannot take.
What to do: Use the values the console offers.
invalid_policy400invalid_request_error
A data policy setting has a value it cannot take, or a number of days outside its range.
What to do: See Data and privacy for each setting's values.
application_not_found404not_found_error
No such application in this organization.
What to do: Refresh the list of applications.
tenant_not_found404not_found_error
No such organization, or you are not a member of it. Both get the same answer.
What to do: Check the link, or ask an admin of the organization to invite you.
zero_retention403permission_error
The console was asked to open a result kept under the zero retention policy, which exists only until the application fetches it.
What to do: Read the result where your application received it; the console never becomes a second reader of it.
role_insufficient403permission_error
Your role in the organization cannot do this.
What to do: Ask an admin or owner, or ask for a higher role.
invalid_role400invalid_request_error
A role is not owner, admin, developer or viewer.
What to do: Choose one of the four.
invalid_email400invalid_request_error
An invitation's email address is not valid.
What to do: Check the address.
already_member409conflict_error
That person is already a member or has been invited.
What to do: Change their role instead.
last_owner409conflict_error
The change would leave the organization without an owner.
What to do: Make someone else an owner first.
credential_required400invalid_request_error
The Playground needs an active key of the chosen application to act as.
What to do: Create or choose an active key.
access_requests_closed403permission_error
ReceViz is not taking new access requests right now.
What to do: Try again later.
organization_required400invalid_request_error
An access request has no organization name.
What to do: Give the organization's name.
use_case_required400invalid_request_error
An access request does not say what you want to extract.
What to do: Describe it in a sentence or two.
request_pending409conflict_error
You already have an access request waiting for review.
What to do: Wait for the decision, or withdraw it first.
request_decided409conflict_error
The access request has already been decided.
What to do: Nothing to do.
Failed extractions
An asynchronous extraction that fails carries its code in error.code rather than in an error response. The codes are the ones on this page, such as pdf_encrypted or processing_timeout, or internal_error.