How do I handle rate limit errors?

When you receive a 429 status, check the Retry-After header for the number of seconds to wait before retrying. Implement exponential backoff for robustness.

What does error code extraction_failed mean?

The extraction pipeline could not process the document. Common causes: corrupted file, unsupported format, or a file that contains no extractable text. Check the error message for details.

Are error responses consistent across all endpoints?

Yes. All Talonic API endpoints return errors in the same JSON format with status, code, and message fields. This makes error handling uniform across your integration.

Error Handling

The Talonic API returns consistent JSON error responses with HTTP status codes, machine-readable error codes, and human-readable messages for every failure.

Error response format

Every error response includes three fields: status (HTTP code), code (machine-readable string), and message (human-readable explanation). Parse the code field for programmatic error handling.

# Example error response
{
  "status": 422,
  "code": "invalid_schema",
  "message": "Schema field 'amount' has unsupported type 'money'. Use 'number' instead."
}

HTTP status codes

Status	Meaning	When it occurs
200	OK	Request succeeded synchronously
202	Accepted	Async job created — poll via /v1/jobs/:id
400	Bad Request	Malformed JSON, missing required field
401	Unauthorized	Missing or invalid API key
403	Forbidden	Key lacks permission for resource
404	Not Found	Resource does not exist
409	Conflict	Resource already exists or version mismatch
422	Unprocessable Entity	Validation error (invalid schema, unsupported type)
429	Too Many Requests	Rate limit exceeded — see Retry-After header
500	Internal Server Error	Unexpected server failure
503	Service Unavailable	Temporary maintenance or overload

Error codes

These machine-readable codes appear in the code field. Use them to handle specific errors programmatically. See authentication for auth-specific errors, rate limits for throttling details, and extract for extraction-specific errors.

Code	Status	Description
invalid_request	400	Malformed request body or missing required parameter
invalid_schema	422	Schema contains unsupported types or invalid structure
invalid_api_key	401	API key is missing, expired, or malformed
forbidden	403	API key lacks required permissions
not_found	404	Requested resource does not exist
conflict	409	Resource version conflict
rate_limited	429	Request rate exceeds plan limits
file_too_large	422	File exceeds plan size limit
unsupported_format	422	File format not supported for extraction
extraction_failed	500	Pipeline could not process the document
confidence_below_gate	422	Extraction confidence below the confidence gate threshold
server_error	500	Unexpected internal error

Retry strategy

For 429 and 503 errors, implement exponential backoff with jitter. The Retry-After header indicates the minimum wait time in seconds. For 500 errors, retry up to three times. Do not retry 400, 401, 403, or 422 errors — these require changes to your request. See the webhook retry policy for delivery-side retries.