Errors

Canonical contract: packages/sdk/docs.md — error hierarchy + ErrorMetadata.

Every error thrown by the SDK extends TheokitAgentError. The hierarchy is closed (no dynamic subclassing) so switch on error.code is exhaustive.

Base class

class TheokitAgentError extends Error {
  code: ErrorCode;        // exhaustive enum
  metadata?: ErrorMetadata; // optional structured context
}

ErrorCode is a finite literal union (ADR D66). ErrorMetadata is an optional field with { provider, endpoint, status, headers, body, rawTruncated } shape (ADR D65, D73).

Hierarchy

TheokitAgentError
├── AuthenticationError       (code: "auth_failed", "missing_api_key")
├── RateLimitError            (code: "rate_limit")
├── ConfigurationError        (code: "invalid_request", "transport_unavailable", ...)
│   └── IntegrationNotConnectedError  (MCP / OAuth not set up)
├── NetworkError              (code: "timeout", "server_error")
├── UnknownAgentError         (code: "unknown")
├── AgentRunError             (code: "agent_run_failed")
├── UnsupportedRunOperationError  (feature not available on this agent variant)
├── CredentialPoolExhaustedError  (all keys cooling down)
└── MemoryAdapterError        (code: MemoryAdapterErrorCode)

Plus feature-scoped errors that also extend TheokitAgentError:

EvalAlreadyRunningError, GenerateObjectError, StreamObjectError, HandoffLoopError, HandoffNameCollisionError, HandoffPairLoopError, HandoffReceiverDisposedError, HandoffSelfReferenceError, CacheEmbedderError, CacheInvalidTtlError, WorkflowAlreadyRunningError, WorkflowCompensateNotImplementedError, WorkflowDuplicateStepIdError, WorkflowMaxIterationsExceededError, WorkflowNotSerializableError, WorkflowParallelError, WorkflowResumeStepNotFoundError, WorkflowSnapshotNotFoundError.

Exhaustive switch

import { TheokitAgentError } from "@theokit/sdk";

try {
  await agent.send("hi");
} catch (err) {
  if (!(err instanceof TheokitAgentError)) throw err;
  switch (err.code) {
    case "auth_failed":     return notify("Re-authenticate");
    case "rate_limit":      return retryWithBackoff(err);
    case "context_too_long": return startNewSession();
    // ... TS forces all cases handled
  }
}

Provider-specific error mappers

Provider HTTP errors are mapped to canonical codes by per-dialect mappers (ADR D67, D300). Bedrock and Vertex have their own mappers; OpenAI and Anthropic share shared.ts. You don't call mappers directly — they run inside the LLM clients.

Redaction

Errors carry metadata.body and metadata.headers for diagnosis. The SDK applies redactSecrets at output boundaries (ADR D73) — logs, telemetry attrs, transcript files. The error object itself contains raw fields; the OUTPUT is sanitized.

API reference