Error Handling

Provider, transport, and orchestration failures use the typed DeuzError contract rather than exposing a raw Response or a provider payload. Each wire adapter normalizes its provider's error envelope into the same set of classes, so retry, routing and fallback logic branches on err.code regardless of which provider produced the failure. The provider taxonomy is exported from the package root. The errors of the agent runtime, its stores and the modules are exported from their own subpaths: see Runtime and module errors.

import { DeuzError, isDeuzError, RateLimitError, AuthenticationError } from '@deuz-sdk/core';

The taxonomy

DeuzError is the abstract base. Every error carries a stable string code; HTTP-shaped errors additionally extend APICallError and carry statusCode plus an isRetryable verdict.

APICallError and its subclasses

APICallError represents a non-2xx response from a provider (or an in-stream error envelope). Adapters map each wire's error type onto one of these.

Every APICallError exposes the same fields:

Non-HTTP errors

These extend DeuzError directly (no statusCode / isRetryable):

ToolExecutionError is constructed internally but, in the agentic loop, it is not thrown. Its message is fed back to the model as an is_error tool_result so the model can self-correct. Look for isError: true on a ToolResult, not for a rejection. See The Tool Loop.

Runtime and module errors

The agent runtime, its stores and the modules raise errors of their own, each exported from the subpath that raises it. They come in two kinds:

• DeuzError subclasses (UnpricedModelError, CheckpointNotFoundError, CheckpointVersionError, RagError, A2AError, BatchError, RealtimeError) carry a code and the secret-safe toJSON(), and isDeuzError recognizes them.
• Plain Error subclasses (the budget, policy, persistence, lease, swarm, evolve and goal errors) carry a name and, all but SwarmConflictError and EvolveConflictError, a code. isDeuzError returns false for them: branch on instanceof, or on name and code.

A native run never rejects with these: runAgent, resumeAgent and the result of streamAgent resolve with status: 'failed' and error: { name, message, code? }, so read result.error.name and result.error.code there. The budget ledger, policy, persistence, lease, unpriced-model and checkpoint-version errors end the run even when they are raised inside a tool (an agentTool sub-agent, for example) or a compaction summary: they never become a tool error the model could retry, or a skipped compaction layer.

Agent runtime

Stores and executors

Modules

Two failure channels, one rule

Which channel a failure uses is decided entirely by whether the entry point is a promise.

The never-throw contract for streamChat

streamChat returns a StreamChatResult synchronously and never throws — not on a missing API key, not on an invalid option pair. The network pump starts lazily on first access of any output. A failure surfaces in three coordinated ways:

1. An { type: 'error', error } part is pushed onto fullStream.
2. The usage promise rejects with that error.
3. The finishReason promise rejects with that error.

Iterating textStream re-throws the error part, so a plain for await over text still lets you try/catch.

import { streamChat, isDeuzError } from '@deuz-sdk/core';
import { createAnthropic } from '@deuz-sdk/core/anthropic';

const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });

const result = streamChat({
  model: anthropic('claude-opus-4-8'),
  messages: [{ role: 'user', content: 'Explain backpressure.' }],
});

try {
  for await (const chunk of result.textStream) {
    process.stdout.write(chunk);
  }
} catch (err) {
  // textStream re-throws the error part as a typed DeuzError.
  if (isDeuzError(err)) console.error(err.code, err.message);
}

Reading error parts off fullStream

If you consume fullStream directly, handle the error part yourself — it will not throw on its own. Keep a default case: StreamPart is an open union.

import { streamChat, DeuzError } from '@deuz-sdk/core';
import { createOpenAI } from '@deuz-sdk/core/openai';

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY! });

const result = streamChat({
  model: openai('gpt-5.5'),
  messages: [{ role: 'user', content: 'hi' }],
});

for await (const part of result.fullStream) {
  switch (part.type) {
    case 'text-delta':
      process.stdout.write(part.text);
      break;
    case 'error':
      if (part.error instanceof DeuzError) {
        console.error(`[${part.error.code}]`, part.error.message);
      }
      break;
    default:
      break; // additive variants
  }
}

generateText and generateObject reject

import { generateObject, NoObjectGeneratedError } from '@deuz-sdk/core';
import { createOpenAI } from '@deuz-sdk/core/openai';
import { z } from 'zod';

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY! });

try {
  const { object } = await generateObject({
    model: openai('gpt-5.5'),
    schema: z.object({ city: z.string(), population: z.number() }),
    messages: [{ role: 'user', content: 'Largest city in Japan?' }],
  });
  console.log(object);
} catch (err) {
  if (err instanceof NoObjectGeneratedError) {
    // The raw model text that failed to parse/validate is on `.text`.
    console.error('No valid object. Raw output:', err.text);
    // 2.3: how the last attempt ended, e.g. 'content_filter' with a refusal's category.
    console.error(err.finishReason, err.stopDetails?.category);
  }
}

generateObject makes one repair retry on a parse/validation failure before throwing. See generateObject.

Catching typed errors

Branch on instanceof for class-specific fields, or on code for a flat switch. The same classes are used across every provider, so this logic is provider-agnostic.

import {
  generateText,
  AuthenticationError,
  RateLimitError,
  ContextOverflowError,
  BreakerOpenError,
  APICallError,
} from '@deuz-sdk/core';
import { createAnthropic } from '@deuz-sdk/core/anthropic';

const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });

try {
  await generateText({
    model: anthropic('claude-opus-4-8'),
    messages: [{ role: 'user', content: 'hello' }],
  });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // 401/403 — bad or insufficient credentials. Do not retry; fix the key.
  } else if (err instanceof RateLimitError) {
    console.log('retry after (ms):', err.retryAfterMs);
  } else if (err instanceof BreakerOpenError) {
    console.log('failing fast until', err.cooldownUntil); // route elsewhere
  } else if (err instanceof ContextOverflowError) {
    // Trim or compact the prompt and try again.
  } else if (err instanceof APICallError) {
    console.error(err.provider, err.statusCode, err.requestId);
  } else {
    throw err; // never swallow what you did not classify
  }
}

Checking retryability

isRetryable lives on APICallError and its subclasses. Errors that are not HTTP-shaped (TimeoutError, AbortError, NoObjectGeneratedError, UnsupportedCapabilityError, BreakerOpenError) do not carry the flag and are final.

import { APICallError } from '@deuz-sdk/core';

function isRetryable(err: unknown): boolean {
  return err instanceof APICallError && err.isRetryable;
}

Retry interplay

The pump retries only before the first byte of the response stream. Once streaming begins, a mid-stream error is final — partial output has already been emitted, so a transparent retry would either duplicate tokens or splice an unrelated completion into the middle of the first.

const result = streamChat({
  model: anthropic('claude-opus-4-8'),
  messages: [{ role: 'user', content: 'hi' }],
  maxRetries: 4, // raise the pre-first-byte budget for this call
});

"Full jitter" rather than a fixed backoff matters at scale: when a provider returns 429 to a hundred of your requests at once, a deterministic delay makes all hundred retry at the same instant and produce a second thundering herd. Randomizing the whole interval spreads them.

The circuit breaker

Retries protect one call. The breaker protects the next ones from a provider that is already down.

• Keyed per provider:modelId and stored in deps.breakerStore — so it is per-client, not global. Two createClient instances do not share a verdict.
• Only provider-health failures count: NetworkError, TimeoutError, and retryable / >= 500 APICallErrors. A 401 or a 400 says nothing about provider health and is ignored.
• 5 consecutive countable failures open it. It then fails fast with BreakerOpenError for a 30s cooldown instead of sending a request.
• A successful response resets the counter (checked the moment a body arrives, before streaming) — best-effort, and only when there was something to clear.
• A failing breaker store never blocks calls — if the store throws, the call proceeds.

fallbackModels and the withFallback middleware treat BreakerOpenError as an immediate fail-over signal, which is the point: the fast failure is what makes fail-over cheap. Full detail on Resilience.

The timeout layers

Each layer answers a different question, so each has its own scope. All are settable per call via timeout, and every timer is scheduled through deps.clock — never an ambient host timer — so tests stay deterministic.

Notes that save debugging time:

• An explicit 0 disables a layer. timeout: { totalMs: 0 } is how you opt out of the 300s ceiling that a 25-second serverless budget makes meaningless.
• ttftMs is not a total budget. A slow-but-alive stream is fine: the timer is cleared the moment any content arrives.
• stepMs is enforced by both loops — the streaming one and the buffered generateText one arm it identically, so the same option cannot mean two things.
• A stepMs expiry that fires while tools are running cannot abort the tools. That is toolMs / Tool.timeoutMs. The loop checks the deadline at its own step boundaries and fails there rather than feeding results into a model call it can no longer pay for.
• A tool timeout is self-healing, not fatal. The execution is abandoned (its signal is aborted, so a well-behaved tool passing it to fetch stops working), and the model receives an is_error tool_result — Tool 'x' timed out after 30000ms and was abandoned. Every tool_use_id still gets a result. Tool timeouts do count toward the runaway-tool guard.

Abort is not a timeout

They look similar and are deliberately kept apart, because "the user changed their mind" and "the provider never answered" call for different handling.

The SDK goes out of its way to keep this true even when a transport misbehaves: if one of our abort sources cut the request but the transport reported only a bare AbortError, the armed TimeoutError is recovered and reported instead of being misread as a user cancel.

Secret redaction (P0)

API keys must never appear in any log, error message, tracer attribute, observation event, or cause chain. This is a regression-tested invariant, not a best effort.

• DeuzError deliberately carries no raw request headers or body, and never places a raw Request/Headers in cause.
• error.toJSON() returns only name, code, message, and an allowlist of scalar diagnostic fields (statusCode, isRetryable, retryAfterMs, provider, requestId, upstreamType, layer, toolName, toolCallId, modelId, capability, runId, mime, serverUrl, and since 2.3 finishReason). A2AError adds its kind, reason and rpcCode, BatchError its kind and batchId, and RealtimeError its kind and closeCode. cause and model output are excluded.
• Anything that flows into a logger, error, or span first passes through the redaction helpers. Secret-looking header values (authorization, x-api-key, x-goog-api-key, api-key) and token shapes (sk-ant-…, sk-…, AIza…, Bearer …) are masked to their last four characters — ****AB12.
• Opt-in observation content capture passes through a second, stricter [REDACTED] profile before an event is emitted.

You never call the redaction helpers yourself; they run inside the SDK. The takeaway: it is safe to log a DeuzError verbatim — including provider, statusCode, requestId and upstreamType — without leaking credentials.

import { generateText, isDeuzError } from '@deuz-sdk/core';

try {
  await generateText({ model, prompt: 'hi' });
} catch (err) {
  // toJSON() is the secret-free projection: name, code, message + scalar details.
  console.error('inference failed', isDeuzError(err) ? err.toJSON() : { message: String(err) });
}

See also

• streamChat — the streaming entry point and the error part.
• generateText — the buffered call that rejects.
• generateObject — structured output and the repair retry.
• Resilience — retry, breaker and fail-over in depth.
• The Tool Loop — how tool failures self-heal instead of throwing.
• Prompts, instructions & timeouts — configuring the timeout layers.