Error Format

All Talonic API errors return a consistent JSON envelope with a machine-readable code, human-readable message, HTTP status, retryable flag, request ID, and timestamp.

All errors return a consistent JSON envelope. The retryable field tells you whether the request can be retried with the same parameters.

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 request_id field (prefixed with req_) uniquely identifies the failed request and is essential for debugging with Talonic support. The path field confirms which endpoint produced the error, and timestamp records when it occurred in ISO 8601 format.

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.

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