Errors and limits | exdata API Docs

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.

Error envelope

{
  "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.

Status	Meaning	Client action
`401`	Missing or invalid API token.	Create or rotate an account token in the app.
`402`	Insufficient credits. The document is returned with `status` `blocked`.	Top up credits or enable auto top-up, then retry the upload.
`403`	The token cannot access the resource or lacks the required ability.	Use a token from the correct account with the required access.
`404`	The resource does not exist or is outside the account.	Check the ID and account context.
`409`	The same `Idempotency-Key` is still processing or was reused with a different payload.	Wait for the original request or use a new key for a different upload.
`422`	The request did not pass validation.	Fix field errors and submit again.
`429`	Token/account rate limit or sandbox limit exceeded.	Back off until `Retry-After` passes, or wait for the next sandbox daily window.

Credit blocking

Live uploads reserve one credit before extraction work is queued. If the account has no available credits, exdata returns 402, marks the document as blocked, and does not dispatch extraction jobs.

Blocked documents

A blocked document keeps the uploaded document record and debugging context. Resolve credits, then retry the upload with a new idempotency key if you want to process it.

Rate limits

Uploads, reads, writes, and authentication attempts are limited by token and account. Test-mode upload limits also return 429 with code test_mode_limit_exceeded and the configured user, account, and token daily limits.