Error Codes

Complete Talonic API error code reference: every machine-readable code with its HTTP status, retryable classification, and the recommended handling for each.

The Talonic API returns one of 17 machine-readable error codes in the code field of every error response. Codes fall into two groups: permanent errors (fix the request before retrying) and retryable errors (retry the same request with exponential backoff). The retryable boolean in the [error envelope](error-format) tells you which group you are in.

Permanent errors (do not retry)

• 400 VALIDATION_ERROR — The request body is malformed, missing required fields, or contains an invalid schema definition.
• 401 AUTH_REQUIRED — Missing or invalid API key.
• 401 TOKEN_EXPIRED — The API key has expired. Generate a new one from the dashboard.
• 402 INSUFFICIENT_CREDITS — Your organization has no remaining credits. Top up from Settings → Billing, or wait for the next Free-plan monthly grant.
• 403 INSUFFICIENT_PERMISSIONS — The API key does not have the required scope for this operation.
• 404 RESOURCE_NOT_FOUND — The requested resource does not exist (or belongs to another workspace).
• 409 DUPLICATE_RESOURCE — A resource with this identifier already exists.
• 413 FILE_TOO_LARGE — The uploaded file exceeds your API tier's upload limit (up to 500 MB on Enterprise). See [Rate Limits](rate-limits).
• 422 EXTRACTION_FAILED — The document could not be processed. Try a different format or check the file.

Retryable errors (retry with backoff)

• 429 QUOTA_EXCEEDED — Daily request limit for the namespace reached. Wait until X-RateLimit-Reset before retrying.
• 429 LLM_RATE_LIMITED — Upstream AI provider rate limit. Retry after 30–60 seconds.
• 500 LLM_TIMEOUT — Upstream AI provider timed out. Retryable with backoff.
• 500 LLM_UNAVAILABLE — Upstream AI provider temporarily unavailable.
• 500 OCR_FAILED — Document OCR failed. May succeed on retry.
• 500 EXTRACTION_TIMEOUT — Extraction exceeded the time limit. Retryable for smaller documents.
• 500 DATASPACE_RUN_FAILED — A platform Job (pipeline run) failed server-side. Retryable with backoff.
• 500 INTERNAL_ERROR — An unexpected server error occurred. Retryable with backoff.

In addition to these canonical codes, input validation on POST /v1/extract returns lowercase error keys specific to that endpoint: missing_document, ambiguous_document, and invalid_options. They are documented in the [extract endpoint errors table](post-extract) and are always 400 and never retryable.

Recommended backoff strategy

For retryable errors, use exponential backoff with jitter:

1. 1st retry — wait 1 second
2. 2nd retry — wait 2 seconds
3. 3rd retry — wait 4 seconds
4. 4th retry — wait 8 seconds
5. 5th retry (max) — wait 16 seconds

Add random jitter (±20%) to avoid thundering herd. For 429 QUOTA_EXCEEDED specifically, respect the X-RateLimit-Reset header instead of using fixed backoff: it tells you exactly when the window resets (ISO 8601 timestamp, midnight UTC). Pair retries of POST requests with an [idempotency key](idempotency) so a retry can never create duplicate work.