HTTP Status Codes
Error Response Format
Every error response follows one JSON structure:
Every response the API answers, a success or an error, carries an
X-Request-ID header. On an error it equals the body’s request_id. Quote it for a success that returned the wrong thing, or for a split’s PDF download that breaks off partway. A 502 or 504 whose body is not JSON comes from the load balancer, not the API, and carries none.
Error Codes Reference
One entry per code a public API caller can receive. The status is the registry default; a route may return a different status for the same code via a per-call override.ACCESS_DENIED
403 · Not retryable
You do not have access to this resource.
How to recover: Use an API key from the organization that owns this resource, or ask one of its admins for access.
AUTH_FAILED
401 · Not retryable
Authentication failed.
How to recover: Send a valid credential in the Authorization: Bearer <key> header and try again.
CONCURRENT_EDIT
409 · Retryable
Someone else changed this at the same time. Reload it and try again.
How to recover: Fetch the resource again, reapply your change and retry.
CONFLICT
409 · Not retryable
The request conflicts with the current state of the resource.
How to recover: Fetch the resource’s current state, resolve the conflict detail names, and send the request again.
DATASET_DOCUMENT_REJECTED
422 · Not retryable
A file in the dataset document was rejected.
How to recover: Read detail for the file that was rejected, fix or remove it, and register the document again.
DATASET_GROUND_TRUTH_SAVE_FAILED
422 · Not retryable
The ground truth could not be saved.
How to recover: Check that the ground truth matches the workflow’s fields, then upload it again.
DATASET_INVALID_REQUEST
422 · Not retryable
The dataset registration request is not valid.
How to recover: Read detail for the part of the request that is not valid, correct it, and send it again.
DATASET_UNSUPPORTED
409 · Not retryable
This workflow does not support datasets.
Params: reason
How to recover: Use a workflow with an Extract node and no Split node for datasets and evals, as params.reason (split or parse_only) names the rule this one breaks.
EMPTY_EVAL
422 · Not retryable
The eval has no rows to run.
How to recover: Add documents with ground truth to the workflow’s dataset before you run an eval.
ENDPOINT_RETIRED
410 · Not retryable
This endpoint has been retired. Use the successor named in the Link header.
How to recover: Call the successor endpoint the Link header names.
EXTRACT_MODE_FORBIDDEN
403 · Not retryable
This organization cannot use that extract mode.
How to recover: Choose an extract mode the organization’s plan includes, or contact support to enable this one.
EXTRACT_NODE_UNRESOLVED
422 · Not retryable
The request does not say which extract node to use.
How to recover: Name in the request the extract node the ground truth belongs to.
FILENAME_CONFLICT
409 · Not retryable
A file with that name already exists.
How to recover: Rename the file, or pass on_conflict=rename, and upload it again.
FILE_TOO_LARGE
413 · Not retryable
The file is larger than the maximum allowed size.
Params: max_bytes
How to recover: Split or compress the file until it is under params.max_bytes bytes, and upload it again.
GATEWAY_TIMEOUT
504 · Retryable
The upstream service did not answer in time.
How to recover: Retry the request with exponential backoff.
GONE
410 · Not retryable
The resource is no longer available.
How to recover: Create the resource again, or use the one that replaced it, because this one was removed.
GRAPH_READBACK_FAILED
502 · Not retryable
The workflow was saved and its graph could not be read back.
How to recover: Fetch the workflow by its ID to read the saved graph, rather than saving it again.
GT_INVALID
422 · Not retryable
The ground truth is not valid.
How to recover: Correct the ground truth against detail so it matches the workflow’s fields, and upload it again.
IDEMPOTENCY_KEY_REUSED
422 · Not retryable
The idempotency key was already used with a different request.
Params: resource_id, resource_type
How to recover: Resend the original request unchanged to get its result, or read the resource it created from params.resource_id; use a new Idempotency-Key only for a genuinely new request.
IMMUTABLE_WORKFLOW
409 · Not retryable
This is a system workflow and it cannot change.
How to recover: Make the change on a workflow of your own, because a system workflow never changes.
INSUFFICIENT_CREDIT
402 · Not retryable
The organization has no extraction credit left.
How to recover: Top up the organization’s credit or upgrade its plan, then run again.
INTERNAL_ERROR
500 · Retryable
An internal error stopped the request.
How to recover: Retry with exponential backoff, and contact support with the request_id if it keeps failing.
INTERNAL_INCONSISTENCY
400 · Not retryable
The server found an internal inconsistency.
How to recover: Contact support with the request_id, because the same request will fail again.
INVALID_API_KEY
401 · Not retryable
The API key is not valid.
How to recover: Check that the key is complete and has not been revoked, or create a new key.
INVALID_JSON
400 · Not retryable
The request body is not valid JSON.
How to recover: Send a body that is valid JSON, with Content-Type: application/json.
INVALID_LOOKUP_FILE_ENCODING
400 · Not retryable
The lookup file uses an encoding the server cannot read.
How to recover: Save the lookup file as UTF-8 and upload it again.
INVALID_VALUE
400 · Not retryable
A value in the request is not valid.
How to recover: Read detail for the value that was rejected, correct it, and send the request again.
INVALID_WORKFLOW_CONFIG
400 · Not retryable
The workflow holds a node configuration that is not valid.
How to recover: Fix the node configuration detail names and save the workflow again.
KNOWLEDGE_DOWNLOAD_UNAVAILABLE
409 · Not retryable
The download archive of this knowledge base cannot be built.
How to recover: Do not retry: change the workflow’s documents so the next version builds, or contact support.
KNOWLEDGE_NOT_ENABLED
409 · Not retryable
The knowledge base is not enabled.
How to recover: Add a knowledge node to the workflow so it starts indexing its documents.
KNOWLEDGE_NOT_READY
409 · Retryable
The knowledge base is not ready yet.
How to recover: Wait for indexing, or for the download archive to be built, to finish, then retry with backoff.
KNOWLEDGE_THREAD_MISMATCH
409 · Not retryable
The thread belongs to another workflow.
How to recover: Use a new thread_id, or ask the workflow the thread belongs to.
KNOWLEDGE_UNSUPPORTED_SNAPSHOT_FORMAT
409 · Not retryable
The knowledge base’s snapshot format is not supported.
How to recover: Contact support to republish the workflow’s knowledge base.
LOOKUP_FIELD_WITHOUT_FILE
400 · Not retryable
A lookup field has no lookup file.
How to recover: Attach a lookup file to every lookup field, or remove the field, and save again.
METHOD_NOT_ALLOWED
405 · Not retryable
The HTTP method is not allowed for this resource.
How to recover: Use an HTTP method the API reference lists for this path.
MISSING_API_KEY
401 · Not retryable
The request carries no API key.
How to recover: Send your API key in the Authorization: Bearer <key> header.
MULTIFILE_UNSUPPORTED
409 · Not retryable
This workflow cannot process a multi-file document.
Params: node_ids
How to recover: Send each file as its own document packet, or change the nodes in params.node_ids: turn agentic mode off on an extract node, or keep a single parse node.
NOT_ACCEPTABLE
406 · Not retryable
No representation matches the request’s Accept header.
How to recover: Send Accept: application/json, or leave the Accept header out.
NOT_ASSIGNED_VERIFIER
403 · Not retryable
Another user is the assigned verifier for this file.
How to recover: Correct this document with the API key of its assigned verifier, or ask an organization admin to remove the verifier in the app.
NOT_FOUND
404 · Not retryable
The resource does not exist.
Params: resource_type
How to recover: Check the ID, and that it belongs to your API key’s organization; params.resource_type names what is missing.
NOT_IMPLEMENTED
501 · Not retryable
This endpoint is not implemented.
How to recover: Use an endpoint the API reference lists, because retrying this one will not help.
NOT_IN_DATASET
409 · Not retryable
The document is not in the workflow’s dataset.
How to recover: Add the document to the workflow’s dataset first, then set ground truth on the dataset’s document packet, not the production one.
OBJECT_STORAGE_UNAVAILABLE
502 · Retryable
Object storage did not complete the request.
How to recover: Retry the request with exponential backoff.
ONESHOT_SIGNALS_MISSING
422 · Not retryable
The one-shot optimization has nothing to learn from.
How to recover: Run documents through the workflow’s dataset first, or send a user_context that describes what the extraction gets wrong, then start it again.
OPERATOR_DEPRECATED
400 · Not retryable
This workflow version uses a deprecated operator and cannot run.
Params: node_ids
How to recover: Replace the operator on the nodes in params.node_ids, save a new version, and run again.
OPERATOR_NOT_AVAILABLE
400 · Not retryable
This workflow uses an operator that is no longer available.
Params: node_ids
How to recover: Replace the operator on the nodes in params.node_ids with a supported one, and save again.
OPTIMIZATION_ALREADY_RUNNING
409 · Retryable
An optimization is already running for this workflow.
How to recover: Wait for the running optimization to finish, then start a new one; list the workflow’s optimizations to see it.
PARSE_MODE_FORBIDDEN
403 · Not retryable
This organization cannot use that parse mode.
How to recover: Choose a parse mode the organization’s plan includes, or contact support to enable this one.
PAYMENT_REQUIRED
402 · Not retryable
Payment is required to continue.
How to recover: Top up the organization’s credit or update its billing, then retry.
PRECONDITION_FAILED
412 · Retryable
The results are not available yet.
How to recover: Poll again with backoff until the results are ready.
RATE_LIMITED
429 · Retryable
Too many requests.
How to recover: Wait the seconds the Retry-After header gives, or back off exponentially without one, then retry.
REPARSE_REQUIRED
400 · Not retryable
The file must be re-parsed before it can be read this way.
How to recover: Re-parse the file, then read the run again.
REQUEST_REJECTED
400 · Not retryable
The backend refused the request with a 4xx status no other code covers.
How to recover: Read detail for the reason, correct the request, and send it again.
REQUEST_TOO_LARGE
413 · Not retryable
The request body is larger than the maximum allowed size.
Params: max_bytes
How to recover: Send a request, and a file, smaller than params.max_bytes bytes.
RUN_IN_PROGRESS
409 · Retryable
A run is still in progress. Wait for it to finish, then delete again.
How to recover: Wait for the run to finish, then delete again.
SERVICE_UNAVAILABLE
503 · Retryable
The service is temporarily unavailable.
How to recover: Retry the request with exponential backoff.
SPLIT_HAS_NO_PAGES
409 · Not retryable
The split holds no pages.
How to recover: Request a split of the run that holds at least one page.
SPLIT_SOURCE_NOT_PDF
409 · Not retryable
The split’s source document is not a PDF.
How to recover: Download the source document itself, because only a PDF source is cut into split PDFs.
TOPOLOGY_INVALID
400 · Not retryable
The workflow topology is not valid.
How to recover: Fix the node connections detail names so the graph is valid, and save again.
UNSUPPORTED_FILE_TYPE
400 · Not retryable
The file type is not supported.
How to recover: Convert the file to a type the API reference lists, and upload it again.
UNSUPPORTED_LOOKUP_FILE
400 · Not retryable
The lookup file type is not supported.
How to recover: Upload the lookup file as UTF-8 text or CSV.
UNSUPPORTED_MEDIA_TYPE
415 · Not retryable
The request media type is not supported.
How to recover: Send the body with the Content-Type the API reference lists for this endpoint.
UPLOAD_SNIFF_BUDGET_EXCEEDED
503 · Retryable
The server could not check the uploaded files in time.
How to recover: Retry with backoff, or register fewer files in one request.
URL_UNREACHABLE
422 · Not retryable
The URL’s hostname could not be resolved.
How to recover: Check that the URL’s hostname resolves in public DNS, then send the request again.
VALIDATION_ERROR
400 · Not retryable
The request failed validation.
How to recover: Read detail for what failed validation, correct the request, and send it again.
WEBHOOK_SUBSCRIPTION_LIMIT
409 · Not retryable
The organization has reached its webhook subscription limit.
How to recover: Delete a webhook the organization no longer needs, then create this one again.
WORKFLOW_CONCURRENT_EDIT
503 · Not retryable
Another request is editing this workflow.
Params: latest_version_id
How to recover: Wait for the other edit to finish, fetch the workflow again, and reapply your change.
WORKFLOW_NAME_CONFLICT
409 · Not retryable
A workflow with that name already exists.
How to recover: Choose a different workflow name and send the request again.
ZERO_DATA_RETENTION_REFUSES_DATASET
409 · Not retryable
This organization keeps no data, so it has no dataset.
How to recover: Keep datasets in an organization that retains data, because a zero-data-retention one cannot hold them.
ZERO_DATA_RETENTION_REFUSES_KNOWLEDGE
409 · Not retryable
This organization keeps no data, so it has no knowledge base.
How to recover: Keep a knowledge base in an organization that retains data, because a zero-data-retention one cannot hold it.
ZERO_DATA_RETENTION_REFUSES_RESULTS_QUERY
409 · Not retryable
This organization keeps no data, so results cannot be filtered or sorted.
How to recover: Filter and sort documents by name, status or date, and read each document’s results on its own, because a zero-data-retention organization’s results are not indexed.
ZERO_DATA_RETENTION_REQUIRED
403 · Not retryable
Only an organization with zero data retention can use this.
How to recover: Call it with an API key of an organization that has zero data retention enabled.
deprecated_operator_ack_required
409 · Not retryable
This workflow uses a deprecated operator, so the save needs an acknowledgement.
Params: node_ids
How to recover: Replace the operator on the nodes in params.node_ids, then save again.
insufficient_api_key_scope
403 · Not retryable
The API key does not carry the scope this call needs.
Params: required_scope
How to recover: Create an API key with the scope params.required_scope names, and use it for this call.
terms_acceptance_required
403 · Not retryable
You must accept the terms of service to continue.
How to recover: Authenticate with an API key, or accept the terms in the web app before using this session.
Authentication Errors
AUTH_FAILED (401). The API key is invalid.Authorization header, or its Bearer token is empty.
Validation Errors
VALIDATION_ERROR (400). Thedetail field holds an array of validation error objects.
Resource Errors
NOT_FOUND (404)Rate Limiting
RATE_LIMITED (429). The response carries aRetry-After header.
Retry-After gives the number of seconds to wait before retrying, and appears only on a 429 response. Every successful response carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset for the tier that applies to that endpoint, extraction or general.
Server Errors
INTERNAL_ERROR (500, or 502/503 when the gateway passes an unstructured upstream failure through with its status)request_id when you contact support; it is the sole correlation handle for an error.

