Errors

The document routes (/v1/documents/* and /v1/extraction-schemas/*) and the Workspaces API (/v1/workspaces/*) use Drex's error envelope with a few extra fields:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_source",
    "message": "source.type must be \"url\", \"parse_result\" or \"workspace_file\"",
    "retryable": false
  },
  "request_id": "req_0123456789abcdef0123456789abcdef"
}

These routes send no issues. Responses from Drex carry their request id in the x-request-id header. Error bodies repeat it as request_id; a successful job body doesn't. A request rejected by the hosting platform before it reaches Drex, such as an oversized body above about 4.5 MB, can return 413 without this JSON envelope or a request id. Handle the HTTP status even when those fields are absent.

Statuses and codesCopy Anchor Link

A file that can't be read, such as a corrupt_file, is accepted but its job ends failed, with the cause in the job's error.code. See The job object.

In the SDKsCopy Anchor Link

Each status raises its own error class. Each class reads type, code and detail from the envelope, and its retryable as server_retryable (Python) or serverRetryable (TypeScript), None or undefined when the body has none:

All of them are NaceAPIError (Python) or APIError (TypeScript). A few cases need a closer look:

• A path that's taken: an upload under 32 MiB to a path that's taken raises the 409 class with code path_conflict. A larger upload, sent in parts, fails its completion job with that code instead, and the SDK raises a plain NaceError whose message names it. See Uploads.
• Mistakes caught before sending: the SDKs refuse these with a plain NaceError: a string source that isn't an https:// URL, a url source with no file_name whose URL doesn't end in a file extension, wait_seconds outside 0 to 60, and an empty Idempotency-Key or one over 200 characters. The SDKs infer file_name from a URL extension when you omit it. For raw HTTP, include source.file_name explicitly, even if the URL ends in .pdf.
• Waiting for a job: jobs.wait raises its own errors for a failed job and for a wait that ran out. See Read a job.
• After a 503 job_pending: the error carries the Idempotency-Key the request sent, as idempotency_key in Python and idempotencyKey in TypeScript. Send the same body with it to resume the job.
• In the CLI: it prints the status, type, code, message and request_id, then up to five of the fields that failed, and exits 1. On job_pending it also prints the key to rerun with as --idempotency-key.

For more on handling errors, see the Python, TypeScript and CLI pages.

Funding cancellationsCopy Anchor Link

A job cancelled because its execution allowance was exhausted can return status: "cancelled" with error.code: "job_cancelled" and error.detail.budget_exhausted: true. This is a job result, rather than an HTTP error status. It is not charged. Prepaid documents have a per-document allowance even when the account has more funds; see Pricing. Resending the same oversized document does not raise that allowance.

Rate limitsCopy Anchor Link

• The limits: creates, upload setup (grants and upload sessions), and job observation (get, list, events, request echoes and parse preview metadata) each have an independent requests-per-minute window per account. Creates allow 120/min free or 600/min paid; job reads allow 600/min free or 3000/min paid (5x); upload setup allows 240/min free or 1200/min paid (2x). An account RPM override scales the same way: 1x creates, 5x reads and 2x upload setup. Unlimited accounts remain uncapped (see Limits). Uploads and polls cannot spend create capacity, and all three windows are separate from inference. File downloads and individual preview parts do not count. NDI can also throttle a call with 429 and Retry-After.

• A create refused with 429: it starts no job and is not billed, and nothing creates it for you later. Retry it yourself, with the same Idempotency-Key, within 13 minutes. A later retry of that key answers 503 job_pending until Drex has confirmed with the document service that no job exists under it, then 422 job_not_created: send the job again under a new key. If the document service did start the job after all, it is linked to your request and billed once, like any other.

• Automatic retries: the SDKs and the CLI retry 408, 429 and 5xx answers on their own, reusing the call's key, and never one marked retryable: false. By default they allow two retries without a total retry budget, so slow failures can take several minutes to surface. An explicit retry budget can stop retries earlier. Saved-schema creates are sent once unless you pass a retry policy. To retry later yourself, pass your own idempotency_key so the retry reuses it. See Errors and retries.

• Request limits: use a document create endpoint and JSON source, such as POST /v1/documents/parse?wait_seconds=60. For a URL source, send a JSON body with source.type set to "url", source.url set to your public HTTPS document URL, and source.file_name set to its filename including the extension (for example, "invoice.pdf"). wait_seconds is a query parameter, not a JSON body field. Keep create bodies under 1,000,000 bytes. The SDKs cap wait_seconds at 60; zero-retention HTTP creates allow up to 100 seconds.

Document batchesCopy Anchor Link

Start with 8 concurrent documents, keeping each worker busy through upload, create and completion. Prefer the SDK option wait_seconds=60 on creates (for raw HTTP, POST /v1/documents/parse?wait_seconds=60, with source.file_name in the JSON source and no wait_seconds body field): it holds that request open for up to 60 seconds, then returns the current job. If it is still running, use jobs.wait rather than a tight polling loop. This reduces requests without changing how the job is billed. See the Python batch example and TypeScript batch example.

A Retry-After response header is the number of seconds to wait before retrying, not a job timeout. The current SDKs honor it automatically with their default retry policy (Python nace-sdk 0.7.0 or later). For a raw HTTP client, wait that long and retry creates with the same Idempotency-Key. Larger batches can still reach the create RPM limit or NDI's own limits; keep concurrency bounded and let retries wait for the window.