Error Format

Handle Talonic API errors with a consistent JSON envelope: machine-readable code, human-readable message, HTTP status, and a retryable flag for safe retries.

Every Talonic API error returns the same JSON envelope: an HTTP statusCode, a machine-readable code, a human-readable message, and a retryable flag that tells you whether the same request can be retried. Because the shape is identical across all endpoints, you can write one error handler for the entire API.

Most integrations parse the code field for programmatic error handling and display the message field to users. A typical error handler checks retryable first: if true, queue the request for retry with exponential backoff; if false, surface the message to the caller and stop.

The path field confirms which endpoint produced the error, and timestamp records when it occurred in ISO 8601 format. Errors from POST /v1/extract may additionally include a request_id (prefixed req_) and a links.dashboard URL pointing at the affected document.

Pair error handling with the [Error Codes](error-codes) reference to map each code value to the correct remediation action. Note that statusCode always matches the HTTP response status, so you can use either for branching logic in your client.

When contacting support about a failed request, include the timestamp, path, and, where present, the request_id from the error body. The request_id links directly to the server-side request trace and speeds up resolution.

Error response envelope

{
  "statusCode": 400,
  "code": "VALIDATION_ERROR",
  "error": "Bad Request",
  "message": "Schema definition is missing required 'type' field at path 'line_items.items'.",
  "retryable": false,
  "timestamp": "2026-04-25T14:30:00.000Z",
  "path": "/v1/schemas"
}

Envelope fields

statusCodeintegerHTTP status code (matches the response status).

codestringMachine-readable error code (e.g. `VALIDATION_ERROR`, `QUOTA_EXCEEDED`). See [Error Codes](error-codes).

errorstringHTTP status text (e.g. "Bad Request", "Too Many Requests").

messagestringHuman-readable explanation of what went wrong.

retryableboolean`true` if the same request may succeed on retry (e.g. rate limits, timeouts).

timestampstringISO 8601 timestamp of when the error occurred.

pathstringThe request path that produced the error.

Some endpoints attach extra context beyond the seven envelope fields. Extraction errors (POST /v1/extract) can carry request_id for tracing and links.dashboard for inspecting the document in the Talonic dashboard. Treat extra fields as optional: your handler should rely only on the envelope fields above.

Error Codes Reference

Rate Limits by Plan

Safe Retries with Idempotency

Error Format

Related