Skip to main content

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.
MISSING_API_KEY (401). The request has no Authorization header, or its Bearer token is empty.
ACCESS_DENIED (403). The API key is valid, but it has no access to this resource.

Validation Errors

VALIDATION_ERROR (400). The detail field holds an array of validation error objects.
INVALID_JSON (400)

Resource Errors

NOT_FOUND (404)

Rate Limiting

RATE_LIMITED (429). The response carries a Retry-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)
GATEWAY_TIMEOUT (504)
Quote the request_id when you contact support; it is the sole correlation handle for an error.

Error Handling Best Practices

1. Check HTTP Status Codes

2. Use Error Codes for Logic

3. Implement Retry Logic

Use exponential backoff for the retryable errors: 5xx and 429.

4. Validate Before Sending

5. Log Errors for Debugging

Testing Error Scenarios

When building your integration, test these common scenarios: