Errors and limits

Error envelope

Every API response includes X-Request-ID. Error bodies include a human-readable message, a machine-readable code, and the request ID you can use for support.

{
  "message": "The uploaded file is not supported.",
  "code": "validation_failed",
  "request_id": "req_01jv2f4v3m8x8r7a1p9d0k2m7q",
  "errors": {
    "file": ["The file must be a supported document type."]
  }
}

HTTP status codes

Handle status codes by category first, then branch on the response code when you need specific client behavior.

Credit availability and usage

Live extraction, analysis, and validation uploads apply credit_cost to the first 1-10 pages before processing begins. Generic extraction, analysis, and validation have a rate of one; an explicitly selected specialized extraction profile can use a different rate. This still applies when allow_ai_processing=false, because that field disables AI only. If available credits do not cover the first band, exdata returns 402, marks the document as blocked, and processing does not begin.

Page-band calculation

Analysis determines the page count asynchronously. Exdata then calculates usage as credit_cost × started 10-page bands. With a rate of 3, 1-10 pages use 3 credits, 11-20 use 6, and 21-30 use 9. The run keeps the calculated total when a usable result or retrievable extracted fields remain. The per-band rate and current net total are available as latest_extraction_run.credit_cost and latest_extraction_run.credits_charged.

Zero-net outcomes

A terminal processing error, including preprocessing failure, returns all applied page-band credits and reports credits_charged: 0 only when neither a usable result nor retrievable extracted fields remain. A completed validation assessment—including not detected, invalid, unsupported, or deterministically not evaluable—is a usable result; technical unavailable is not. Test-mode extraction runs also report zero. Reprocessing after an already charged result reports zero; reprocessing after a fully returned failure receives a new page-band charge if it first leaves a usable result or retrievable extracted fields. Thumbnail-only documents have zero credit usage and no extraction run.

A blocked extraction document keeps the uploaded document record and debugging context. Resolve the account condition, then submit a new logical upload with a new idempotency key if you want to process it.

Rate limits

API requests are limited across several time windows. Authenticated requests can be limited by API token or workspace, test-mode uploads can also be limited by user, and anonymous routes can be limited by IP address. A request must remain within every policy that applies to it.

Upload capacity

Live and test-mode uploads use the workspace's effective profile. Every upload must remain within all five limits in its profile.

standard is the current default production profile. The API tokens page shows the effective profile and current upload capacity for your workspace. Use those values and the response rate-limit headers when sizing your integration.

Profile availability

Additional capacity profiles may become available as your workspace meets the applicable eligibility requirements. The API tokens page always shows the profile and limits currently applied to your workspace.

Read and delete capacity

Reads and deletes follow the same profile as uploads, so a workspace can always retrieve and remove documents at least as fast as it can create them. Deletes cover DELETE /documents/{id}; every other authenticated GET counts as a read.

Polling a large batch spends the read budget quickly. Poll each document on a backoff rather than in a tight loop, and delete a document as soon as it reaches a terminal status so cleanup keeps pace with uploads.

Other API limits

Reads, deletes, test-mode uploads, and anonymous x402 routes use these additional limits. Anonymous x402 uploads currently return 503; use authenticated REST uploads instead. Test-mode uploads must satisfy both their upload profile and the daily sandbox limits.

Response headers

A rate-limited response uses status 429. The headers identify the policy that rejected the request and when it can be retried.

Responses with code rate_limited repeat these details as rate_limit_profile, rate_limit_scope, rate_limit_window, rate_limit_limit, and retry_after in the JSON body. Test-mode daily limits use code test_mode_limit_exceeded, include their account, user, and token limits, and include the same retry_after delay as the Retry-After header.