Skip to main content

Error Classes

Every failure is a TalonicError subclass with status, code, retryable, and requestId properties. The class hierarchy maps HTTP status codes to specific error types so you can handle each failure category independently.

Available error classes
import {
  TalonicError,           // base class — catches all SDK errors
  TalonicAuthError,       // 401, 403 — invalid key or insufficient permissions
  TalonicNotFoundError,   // 404 — resource does not exist
  TalonicValidationError, // 400, 409, 413, 422 — bad input, conflict, file too large
  TalonicRateLimitError,  // 429 — rate limited (after retries exhausted)
  TalonicServerError,     // 500, 502, 503, 504 — server error (after retries exhausted)
  TalonicNetworkError,    // DNS / TCP failures — status: 0, code: 'network_error'
  TalonicTimeoutError,    // request exceeded configured timeout — status: 0, code: 'timeout'
} from '@talonic/node'

Each error class maps to a specific failure category. TalonicAuthError covers authentication and permission failures (401, 403). TalonicValidationError covers request rejections like bad input, conflicts, oversized files, or unprocessable entities (400, 409, 413, 422). TalonicRateLimitError and TalonicServerError are only thrown after all retries are exhausted.

Error class properties
// Every TalonicError subclass carries these properties:
try {
  await talonic.extract({ file_path: './doc.pdf', schema_id: 'sch_invalid' })
} catch (err) {
  if (err instanceof TalonicError) {
    err.code       // 'invalid_schema' — machine-readable error code
    err.status     // 422 — HTTP status (0 for network/timeout)
    err.message    // 'Schema sch_invalid not found' — human-readable
    err.retryable  // false — was this error retried?
    err.requestId  // 'req_abc123' — server trace ID (undefined for transport errors)
    err.name       // 'TalonicValidationError' — class name
  }
}

TalonicNetworkError and TalonicTimeoutError represent transport-level failures that never reached the server. Both carry status: 0 and are retried automatically. The code property is set to "network_error" or "timeout" respectively, and retryable is always true. TalonicNetworkError preserves the original error as cause for debugging DNS failures, TCP resets, and unreachable hosts. TalonicTimeoutError includes a timeoutMs property with the configured timeout value that was exceeded.

Transport-level error details
import { TalonicNetworkError, TalonicTimeoutError, TalonicRateLimitError } from '@talonic/node'

try {
  await talonic.extract({ file_path: './doc.pdf', schema_id: 'sch_abc123' })
} catch (err) {
  if (err instanceof TalonicTimeoutError) {
    console.error(`Request timed out after ${err.timeoutMs}ms`)
    // err.status === 0, err.code === 'timeout', err.retryable === true
  }

  if (err instanceof TalonicNetworkError) {
    console.error(`Network failure: ${err.message}`)
    console.error(`Original error: ${err.cause}`) // underlying DNS/TCP error
    // err.status === 0, err.code === 'network_error', err.retryable === true
  }

  if (err instanceof TalonicRateLimitError) {
    console.error(`Rate limited. Limit: ${err.rateLimit.limit}, remaining: ${err.rateLimit.remaining}`)
    console.error(`Resets at: ${err.rateLimit.resetAt.toISOString()}`)
    // err.rateLimit provides { limit, remaining, resetAt } from response headers
  }
}

All error classes extend the base TalonicError, so a single catch with instanceof TalonicError captures every SDK failure. Use more specific subclasses when you need to branch on failure mode, such as showing a different message for auth errors versus validation errors. The TalonicRateLimitError is unique in carrying a rateLimit property with limit, remaining, and resetAt (Date) from the response headers, useful for scheduling manual retries after the SDK's own retries are exhausted.

The SDK also throws client-side TalonicError instances (not subclasses) for parameter validation failures before any network request is made. These carry status: 0, retryable: false, and codes like missing_file_source, multiple_file_sources, multiple_schemas, or missing_field_reference. They indicate programming errors in how the SDK is called rather than server-side failures.

Every error includes a requestId property (when available) that maps to the server-side request log. Include it in support tickets for fast debugging.

Frequently asked questions

What error types does the Talonic SDK throw?+
The SDK throws typed subclasses of TalonicError: TalonicAuthError (401/403), TalonicNotFoundError (404), TalonicValidationError (400/409/413/422), TalonicRateLimitError (429), TalonicServerError (5xx), TalonicNetworkError, and TalonicTimeoutError. Client-side validation errors use the base TalonicError class.
What is the requestId property on errors?+
It is a server-assigned identifier for the request that failed. Include it in support tickets or logs for fast debugging. It may be undefined for transport-level errors (network, timeout) that never reached the server, and for client-side validation errors.
Are TalonicNetworkError and TalonicTimeoutError retried automatically?+
Yes. Both are marked retryable: true and the SDK retries them up to maxRetries times with exponential backoff. They are only thrown after all retry attempts are exhausted.
What client-side validation errors does the SDK throw?+
The SDK throws TalonicError (base class) with status 0 and retryable false for parameter validation failures: missing_file_source (no file provided to extract), multiple_file_sources (more than one file source), multiple_schemas (both schema and schema_id provided), and missing_field_reference (filter condition without field or fieldId).
How does TalonicRateLimitError differ from other error classes?+
TalonicRateLimitError uniquely carries a rateLimit property with limit (max requests per window), remaining (requests left), and resetAt (Date when the window resets). This data comes from the X-RateLimit-* response headers and is useful for scheduling manual retries or implementing backpressure in your application.

Related

Error Handling
Retries & Backoff