The platform’s typed error surfaces — the subsystems that declare their failures as enumerable codes, generated from source so the catalog stays in lockstep. Each entry names the failure and, where the subsystem declares it, whether it is retryable or terminal — the contract a caller routes on (retry, failover, surface-to-user, page on-call).
43Error codes
3Typed surfaces
5Retryable
8Terminal
retryable safe to retry / failover-eligible · terminal not retryable without a change · HTTP nnn the status a client sees. Scope: this is the catalog of subsystems with a declared, typed error surface — not every error the platform can raise; ad-hoc failures live in each subsystem’s deep-dive (§7), not a fabricated central table.
LLM gateway (19)#
The typed error hierarchy emitted by the LLM gateway. Callers instanceof these to decide retry, failover, surface-to-user, or page-on-call — so retryable is the contract, not a hint. source.
Auth failure — missing/expired API key. Not retryable without rotation.
authorization#Caller cancelled via `AbortSignal`. Not retryable.
Circuit breaker open — provider is being skipped. Failover-eligible.
content_filter#Input + max-output exceeds the model's context window. Not retryable.
Malformed request — schema validation, missing required fields, etc.
malformed_response#Network-layer failure (DNS, TCP, TLS, connection reset). Retryable.
Per-tenant quota cap reached. Not retryable in-window.
* @oshun/contracts/llm - Error Taxonomy * * Typed error hierarchy emitted by `IsisLLMClient`. Consumers `instanceof` * these classes to make routing decisions (retry, fallback, surface to * user, page on-call). Every error carries `code`, `provider`, `model`, * `requestId`, `retryable`, and an optional `retryAfterMs`. */ import { z } from 'zod'; import { LLMProviderSchema, LLMRequestIdSchema, type LLMProvider, type LLMRequestId, } from './primitives'; // ============================================================================ // Error code enumeration (used by both error classes and persisted records) // ============================================================================ export const LLMErrorCodeSchema = z.enum([ 'rate_limit', 'quota_exceeded', 'context_length_exceeded', 'invalid_request', 'authentication', 'authorization', 'safety_filter', 'content_filter', 'provider_unavailable', 'circuit_breaker_open', 'timeout', 'cancelled', 'network', 'malformed_response', 'unsupported_model', 'unsupported_capability', 'tool_validation', 'structured_output_validation', 'unknown', ]); export type LLMErrorCode = z.infer<typeof LLMErrorCodeSchema>; /** Persisted error record (e.g., for audit logs / replay). */ export const LLMErrorRecordSchema = z.object({ code: LLMErrorCodeSchema, provider: LLMProviderSchema, model: z.string().min(1).max(120).nullable(), requestId: LLMRequestIdSchema.nullable(), message: z.string().min(1).max(4000), retryable: z.boolean(), retryAfterMs: z.number().int().min(0).nullable().default(null), upstreamStatus: z.number().int().min(0).max(599).nullable().default(null), upstreamCode: z.string().min(1).max(200).nullable().default(null), occurredAtEpochMs: z.number().int().min(0), }); export type LLMErrorRecord = z.infer<typeof LLMErrorRecordSchema>; // ============================================================================ // Base class // ============================================================================ export interface LLMErrorOptions { readonly provider: LLMProvider; readonly model: string | null; readonly requestId: LLMRequestId | null; readonly retryable?: boolean; readonly retryAfterMs?: number | null; readonly upstreamStatus?: number | null; readonly upstreamCode?: string | null; readonly cause?: unknown; } /** Base class. All gateway errors extend this. */ export class LLMError extends Error { public readonly code: LLMErrorCode; public readonly provider: LLMProvider; public readonly model: string | null; public readonly requestId: LLMRequestId | null; public readonly retryable: boolean; public readonly retryAfterMs: number | null; public readonly upstreamStatus: number | null; public readonly upstreamCode: string | null; public readonly occurredAtEpochMs: number; constructor(code: LLMErrorCode, message: string, options: LLMErrorOptions) { super(message, options.cause !== undefined ? { cause: options.cause } : undefined); this.name = this.constructor.name; this.code = code; this.provider = options.provider; this.model = options.model; this.requestId = options.requestId; this.retryable = options.retryable ?? false; this.retryAfterMs = options.retryAfterMs ?? null; this.upstreamStatus = options.upstreamStatus ?? null; this.upstreamCode = options.upstreamCode ?? null; this.occurredAtEpochMs = Date.now(); } /** Serialise to a `LLMErrorRecord` for logging / persistence. */ toRecord(): LLMErrorRecord { return { code: this.code, provider: this.provider, model: this.model, requestId: this.requestId, message: this.message, retryable: this.retryable, retryAfterMs: this.retryAfterMs, upstreamStatus: this.upstreamStatus, upstreamCode: this.upstreamCode, occurredAtEpochMs: this.occurredAtEpochMs, }; } } // ============================================================================ // Concrete subclasses // ============================================================================ /** 429 / token-bucket exhaustion. Always retryable.
Provider-side safety filter blocked the request or response. Not retryable.
Structured-output reply failed JSON-schema validation.
Request exceeded `LLMRequest.timeoutMs`. Retryable.
Tool input failed JSON-schema validation. Not retryable without prompt change.
unknown#unsupported_capability#unsupported_model#Neith API (5)#
The HTTP-facing error registry for the Neith inverse-modeling API — each code carries a stable identifier, HTTP status, and the failure it names. The full record (causes, resolutions, worked example) lives in source. source.
The uploaded asset exceeds the maximum file size limit for your plan.
The requested asset does not exist or has been deleted.
The request requires a valid API key or Bearer token. None was provided or the provided credential is invalid.
The authenticated user does not have permission to perform the requested operation on this resource.
You have exceeded the API rate limit. Requests are throttled per API key.
Uzume media pipeline (19)#
The Uzume media pipeline namespaces every failure under a SUBSYSTEM-NNN code across 19 subsystems, so an operator can route a failure to its owning subsystem from the code alone. source.
LUMINA-NNN#LUMINA subsystem failures (sequence 001–999).
SONOS-NNN#SONOS subsystem failures (sequence 001–999).
PRISM-NNN#PRISM subsystem failures (sequence 001–999).
KINESIS-NNN#KINESIS subsystem failures (sequence 001–999).
PYRA-NNN#PYRA subsystem failures (sequence 001–999).
SCENA-NNN#SCENA subsystem failures (sequence 001–999).
KORU-NNN#KORU subsystem failures (sequence 001–999).
NEXUS-NNN#NEXUS subsystem failures (sequence 001–999).
ATLAS-NNN#ATLAS subsystem failures (sequence 001–999).
AEGIS-NNN#AEGIS subsystem failures (sequence 001–999).
AURORA-NNN#AURORA subsystem failures (sequence 001–999).
ECHO-NNN#ECHO subsystem failures (sequence 001–999).
VESTIS-NNN#VESTIS subsystem failures (sequence 001–999).
PREVIZ-NNN#PREVIZ subsystem failures (sequence 001–999).
CHRONOS-NNN#CHRONOS subsystem failures (sequence 001–999).
TESLA-NNN#TESLA subsystem failures (sequence 001–999).
HERMES-NNN#HERMES subsystem failures (sequence 001–999).
FORGE-NNN#FORGE subsystem failures (sequence 001–999).
MUSE-NNN#MUSE subsystem failures (sequence 001–999).
Codes follow <SUBSYSTEM>-<NNN> (a 001–999 sequence per subsystem); the 19 subsystem prefixes are listed above.