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
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<string, string | number | boolean | null> >;
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.
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.
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
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
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
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
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
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