> ## Documentation Index > Fetch the complete documentation index at: https://deepline.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Errors And Provider Fallthrough New Plays receive typed tool errors. Existing published artifacts keep the error contract stored with their revision. For a read waterfall, catch only `ProviderTransientError` and keep the final provider call loud. For structured diagnostics, narrow to `ToolExecutionError` and branch on its stable fields. Never branch on `error.message`. A newly authored Play can explicitly retain legacy errors with `compatibility: { toolErrorSchemaVersion: 0 }` in the play `export const config = { ... }`. Use that only while migrating old message-based handling. ### `DeeplineError` Base error class shared by the SDK and play runtime. The global brand preserves `instanceof DeeplineError` when a bundled play and the runtime load separate physical copies of this module. Signature: `class DeeplineError extends Error` #### Members | Member | Kind | Purpose | Parameters | Returns / type | | - | - | - | - | - | | `constructor` | constructor | Construct a Deepline error. SDK and runtime code construct these errors. Application and Play code normally catches the public subclasses instead. | `message: string` - Human-readable failure summary. `statusCode?: number` - HTTP status when one exists. `code?: string` - Stable machine-readable code when one exists. `details?: Record` - Local diagnostic context. Never a portable error contract. | | | `statusCode` | property | HTTP status when the failure crossed an HTTP boundary. | | `number` | | `code` | property | Stable machine-readable error code when one exists. | | `string` | | `details` | property | Local diagnostic context. Not a portable error contract. | | `Record` | ### `ToolExecutionErrorOrigin` The boundary responsible for a failed tool call. Use `provider` to distinguish a provider answer from caller input and Deepline infrastructure. `unknown` fails closed and must not trigger a waterfall fallback.\ Signature: `export type ToolExecutionErrorOrigin = | 'caller' | 'provider' | 'deepline' | 'unknown';` ### `ToolExecutionErrorCategory` The stable reason family for a failed tool call. Branch on this field only after narrowing to `ToolExecutionError`. Catch `ProviderTransientError` when the policy is simply “try the next read provider”. It is the safer and shorter waterfall contract.\ Signature: `export type ToolExecutionErrorCategory = | 'validation' | 'authentication' | 'authorization' | 'rate_limit' | 'network' | 'upstream' | 'billing' | 'conflict' | 'internal' | 'unknown';` ### `ToolExecutionNetworkKind` The transport failure observed when `category` is `network`. This is `null` for failures that are not network failures.\ Signature: `export type ToolExecutionNetworkKind = | 'timeout' | 'dns' | 'connect' | 'reset' | 'unavailable' | 'unknown';` ### `ToolExecutionNetworkScope` The request boundary on which a network failure occurred. `deepline_to_provider` is provider-side. Client and runtime scopes are Deepline transport failures and never qualify as provider fallthrough.\ Signature: `export type ToolExecutionNetworkScope = | 'client_to_deepline' | 'runtime_to_deepline' | 'deepline_to_provider';` ### `ProviderTransientErrorCategory` Provider-owned failure categories that may fall through to another read provider.\ Signature: `export type ProviderTransientErrorCategory = | 'rate_limit' | 'network' | 'upstream';` ### `ToolExecutionPublicDetails` Bounded, primitive-only diagnostics explicitly approved for customers. Raw provider bodies, credentials, prompts, stacks, and causes never belong in this shared API/SDK/Play contract.\ Signature: `export type ToolExecutionPublicDetails = Readonly< Record >;` ### `ToolExecutionFailureV1` Portable version-1 `tool_error` payload. This allowlisted shape crosses the API, runtime, and SDK boundaries. `message` remains on the Error object and is deliberately not a policy field. | Name | Type | Required | Description | | - | - | -: | - | | `schemaVersion` | `typeof TOOL_EXECUTION_ERROR_SCHEMA_VERSION` | Yes | Payload version. | | `toolId` | `string` | Yes | Public tool id passed to `tools.execute`. | | `provider` | `string \| null` | Yes | Provider responsible for the operation, or `null`. | | `operation` | `string \| null` | Yes | Provider operation name, or `null`. | | `code` | `string \| null` | Yes | Stable machine-readable failure code, or `null`. | | `origin` | `ToolExecutionErrorOrigin` | Yes | Boundary responsible for the failure. | | `category` | `ToolExecutionErrorCategory` | Yes | Stable reason family. | | `retryable` | `boolean` | Yes | Whether repeating the same semantic call is delivery-safe. | | `statusCode` | `number \| null` | Yes | HTTP status when one exists, or `null`. | | `requestId` | `string \| null` | Yes | Provider or Deepline request id, or `null`. | | `retryAfterMs` | `number \| null` | Yes | Suggested same-call retry delay in milliseconds, or `null`. | | `networkKind` | `ToolExecutionNetworkKind \| null` | Yes | Network failure kind, or `null`. | | `networkScope` | `ToolExecutionNetworkScope \| null` | Yes | Network boundary that failed, or `null`. | | `publicDetails` | `ToolExecutionPublicDetails \| null` | No | Explicitly allowlisted customer diagnostics, when present. | ### `ToolExecutionErrorOptions` Constructor input for a structured tool failure. Deepline creates these values while decoding the versioned wire payload. Customer code normally reads `ToolExecutionError` fields instead of constructing an error. | Name | Type | Required | Description | | - | - | -: | - | | `details` | `Record` | No | Local diagnostic context inherited from DeeplineError. This is not part of the portable failure payload and is intentionally omitted by serialization. | ### `ToolExecutionError` A failed `tools.execute` call with stable, allowlisted provenance. `retryable` means Deepline's delivery/idempotency contract says it is safe to repeat the same semantic call. It does not describe durable receipt repairability and does not make arbitrary side-effecting fallbacks safe. In a Play, catch `ProviderTransientError` to continue a read waterfall and let every other `ToolExecutionError` remain loud. In an SDK client, catch this base class when you need structured diagnostics for every tool failure. Signature: `class ToolExecutionError extends DeeplineError` #### Members | Member | Kind | Purpose | Parameters | Returns / type | | - | - | - | - | - | | `constructor` | constructor | Construct a structured tool error. Deepline constructs this from the versioned `tool_error` payload. Application and Play code should catch it rather than create it. | `message: string` `options: ToolExecutionErrorOptions` | | | `toolId` | property | Public tool id passed to `tools.execute`. | | `string` | | `provider` | property | Provider responsible for the operation, or `null` when unattributed. | | `string \| null` | | `operation` | property | Provider operation name, or `null` when unavailable. | | `string \| null` | | `origin` | property | Boundary responsible for the failure. | | `ToolExecutionErrorOrigin` | | `category` | property | Stable reason family for policy and diagnostics. | | `ToolExecutionErrorCategory` | | `retryable` | property | Whether repeating the same semantic call is delivery-safe. This does not mean the error may be ignored. Waterfall fallthrough is represented by `ProviderTransientError`. | | `boolean` | | `requestId` | property | Provider or Deepline request id, or `null` when unavailable. | | `string \| null` | | `retryAfterMs` | property | Suggested same-call retry delay in milliseconds, or `null`. | | `number \| null` | | `networkKind` | property | Network failure kind, or `null` for non-network failures. | | `ToolExecutionNetworkKind \| null` | | `networkScope` | property | Network boundary that failed, or `null` for non-network failures. | | `ToolExecutionNetworkScope \| null` | | `publicDetails` | property | Explicitly allowlisted diagnostics safe for SDK and Play callers. | | `ToolExecutionPublicDetails \| null` | ### `ProviderTransientError` A provider-owned transient failure that is safe to handle as an empty waterfall leg. Validation, auth, billing, Deepline, and unknown failures never satisfy this type. `retryable` remains independent: it says whether the same semantic call may be repeated safely. Falling through to a different read provider depends on this class, not on `retryable`. Signature: `class ProviderTransientError extends ToolExecutionError` #### Members | Member | Kind | Purpose | Parameters | Returns / type | | - | - | - | - | - | | `constructor` | constructor | Constructed by Deepline when a provider-owned transient failure arrives. | `message: string` `options: Omit & { category: ProviderTransientErrorCategory; }` | | | `origin` | property | Provider attribution is guaranteed for this subtype. | | `"provider"` | | `category` | property | Provider failure category that made this error eligible for fallthrough. | | `ProviderTransientErrorCategory` | ### `AuthError` Thrown when the API rejects the request due to an invalid or missing API key. This maps to HTTP 401 responses. HTTP 403 means the caller was authenticated but lacks permission, so the SDK preserves the server's API error instead. The SDK never retries auth errors — they fail immediately. Fix: run `deepline auth register` to obtain a valid key, or pass one via the `apiKey` option or `DEEPLINE_API_KEY` environment variable. Signature: `class AuthError extends DeeplineError` #### Members | Member | Kind | Purpose | Parameters | Returns / type | | - | - | - | - | - | | `constructor` | constructor | Constructed by the SDK when Deepline rejects the caller's credentials. | `message?: string` | | ### `RateLimitError` Thrown when the API returns HTTP 429 (Too Many Requests). The SDK retries rate-limited requests automatically up to `maxRetries` times with exponential backoff. This error is only thrown when all retries are exhausted. Use `RateLimitError.retryAfterMs` to implement your own backoff if needed. Signature: `class RateLimitError extends DeeplineError` #### Members | Member | Kind | Purpose | Parameters | Returns / type | | - | - | - | - | - | | `constructor` | constructor | Constructed by the SDK after exhausting HTTP-level rate-limit retries. | `retryAfterMs?: number` `message?: string` | | | `retryAfterMs` | property | Milliseconds to wait before retrying, from the `Retry-After` response header. Defaults to 5000. | | `number` | ### `ToolRateLimitError` Tool-specific 429 preserving both historical RateLimitError catches and the structured ToolExecutionError ontology. JavaScript has one prototype chain, so this class extends RateLimitError and carries ToolExecutionError's stable cross-bundle brand. This class appears in external SDK calls after HTTP 429 retries are exhausted. It also satisfies `instanceof ToolExecutionError` and, for a provider-owned rate limit, `instanceof ProviderTransientError`. Authored Plays should use `ProviderTransientError`. they do not need this compatibility class. Signature: `class ToolRateLimitError extends RateLimitError` #### Members | Member | Kind | Purpose | Parameters | Returns / type | | - | - | - | - | - | | `constructor` | constructor | Constructed by the SDK after a structured tool HTTP 429. | `message: string` `options: ToolExecutionErrorOptions` | | | `toolId` | property | Public tool id passed to `tools.execute`. | | `string` | | `provider` | property | Provider responsible for the operation, or `null`. | | `string \| null` | | `operation` | property | Provider operation name, or `null`. | | `string \| null` | | `code` | property | Stable machine-readable failure code when one exists. | | `string \| undefined` | | `origin` | property | Boundary responsible for the failure. | | `ToolExecutionError['origin']` | | `category` | property | Stable reason family for policy and diagnostics. | | `ToolExecutionError['category']` | | `retryable` | property | Whether repeating the same semantic call is delivery-safe. | | `boolean` | | `requestId` | property | Provider or Deepline request id, or `null`. | | `string \| null` | | `networkKind` | property | Network failure kind, or `null` for non-network failures. | | `ToolExecutionError['networkKind']` | | `networkScope` | property | Network boundary that failed, or `null` for non-network failures. | | `ToolExecutionError['networkScope']` | | `publicDetails` | property | Explicitly allowlisted diagnostics safe for SDK callers. | | `ToolExecutionError['publicDetails']` | ### `ConfigError` Thrown when the SDK cannot resolve a valid configuration. Most commonly: no API key found in any of the resolution sources (explicit option, environment variable, CLI env files). Signature: `class ConfigError extends DeeplineError` #### Members | Member | Kind | Purpose | Parameters | Returns / type | | - | - | - | - | - | | `constructor` | constructor | Construct a local SDK configuration failure. | `message: string` | | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.