/** * Provider-SHAPED error bodies (spec §3b). The gateway NEVER leaks pool * internals — pool/auth failures surface only as provider-style availability / * rate-limit / auth errors. Two shapes: Anthropic and OpenAI. * * Mapping (spec §3b): * 401 caller-auth-fail -> provider auth-error * 401 upstream-auth-failed (BR77) -> provider auth-error (NOT pooled 503) * 429 over-budget (BR-47) -> provider rate-limit + Retry-After * 429 upstream-rate-limited (BR77) -> provider rate-limit + Retry-After * 429 no-eligible-account -> provider overloaded + Retry-After * 503 caller-auth-unavailable -> provider overloaded, auth-subsystem message * 503 pooled-account-unavailable -> provider overloaded, account-subsystem message (NOT pool detail) * 503 budget-unavailable (BR-47) -> provider overloaded, budget-subsystem message (NOT pricing/store detail) * 400 bad-request -> provider invalid-request * 404 unknown-model (Lot 1) -> provider not-found (model-only message) * 503 no-route (BR-REL-Q7) -> provider api/server error + x-should-retry:false * The gateway maps internal failure CLASSES to these — callers see only the * provider-shaped surface, never `no_account` / lease / reservation internals. */ import type { GatewayWire } from '../ports/dispatch.js'; import type { ResolvedTarget } from '../flow.js'; import { type RequestSizeDetail } from '@sentropic/llm-mesh'; export interface ProviderShapedError { readonly status: number; readonly body: unknown; /** Optional headers (e.g. `Retry-After`) to attach to the response. */ readonly headers?: Readonly>; } /** * Internal failure classes the flow raises. Mapped to provider-shaped errors * per wire by `mapGatewayError`. These names NEVER reach the client body. */ export type GatewayFailureKind = 'caller-auth-failed' | 'caller-auth-unavailable' | 'over-budget' | 'no-eligible-account' | 'pooled-account-unavailable' | 'budget-unavailable' | 'upstream-auth-failed' | 'upstream-rate-limited' | 'bad-request' | 'native-required' | 'native-max-tokens-required' | 'native-unavailable' | 'unknown-model' | 'no-route' | 'request-too-large' | 'request-body-capacity' | 'cross-user-disabled' | 'guard-blocked' | 'protected-identification-mutated'; export interface NativeValidationPublicDetail { readonly type: string; readonly message: string; } export declare class GatewayError extends Error { readonly kind: GatewayFailureKind; /** Seconds for a `Retry-After` header, when the kind warrants one. */ readonly retryAfterSeconds?: number | undefined; /** Present only after a provider/model has been selected for dispatch. */ readonly servedTarget?: ResolvedTarget | undefined; /** * Client-safe bad-request code (spec §16.7: `bad_request` or * `unsupported_parameter`). Rendered only for `bad-request` on * OpenAI-shaped wires; every other kind stays frozen. */ readonly code?: string | undefined; /** * Client-safe field path: gateway-built literals, plus unknown caller * keys echoed charset-gated (a restricted echo to the caller itself, * never a reflection vector). Rendered only for `bad-request` on * OpenAI-shaped wires. */ readonly param?: string | undefined; /** Trusted measured size for `request-too-large`; never caller text. */ readonly requestSize?: RequestSizeDetail | undefined; /** Public validation detail for native 400 fidelity; excluded from logs/ledgers. */ readonly validation?: NativeValidationPublicDetail | undefined; constructor(kind: GatewayFailureKind, /** Internal, redaction-safe detail for logs — NEVER sent to the client. */ message: string, /** Seconds for a `Retry-After` header, when the kind warrants one. */ retryAfterSeconds?: number | undefined, /** Present only after a provider/model has been selected for dispatch. */ servedTarget?: ResolvedTarget | undefined, /** * Client-safe bad-request code (spec §16.7: `bad_request` or * `unsupported_parameter`). Rendered only for `bad-request` on * OpenAI-shaped wires; every other kind stays frozen. */ code?: string | undefined, /** * Client-safe field path: gateway-built literals, plus unknown caller * keys echoed charset-gated (a restricted echo to the caller itself, * never a reflection vector). Rendered only for `bad-request` on * OpenAI-shaped wires. */ param?: string | undefined, /** Trusted measured size for `request-too-large`; never caller text. */ requestSize?: RequestSizeDetail | undefined, /** Public validation detail for native 400 fidelity; excluded from logs/ledgers. */ validation?: NativeValidationPublicDetail | undefined); } export declare const anthropicError: (status: number, type: string, message: string, headers?: Readonly>) => ProviderShapedError; export declare const openAiError: (status: number, type: string, message: string, code?: string, headers?: Readonly>, param?: string) => ProviderShapedError; export interface FieldError { readonly code?: string; readonly param?: string; } /** * Map an internal failure class to a provider-shaped error for the wire. The * CLIENT-FACING message is a fixed, pool-internal-free string per class, * except for the diagnostic trust boundary: `no-route` appends * mesh-authored availability detail, and the enrollment-action branch * prefers the mesh-authored message over the rebuilt template. The * internal `error.message` (with any account/lease detail) stays in logs only. */ export declare const mapGatewayError: (wire: GatewayWire, kind: GatewayFailureKind, retryAfterSeconds?: number, requestedModel?: string, detail?: string, field?: FieldError, requestSize?: RequestSizeDetail, validation?: NativeValidationPublicDetail) => ProviderShapedError; /** Map a thrown `GatewayError` (or unknown error) to a provider-shaped error. */ export declare const toProviderShapedError: (wire: GatewayWire, error: unknown, requestedModel?: string) => ProviderShapedError; /** Terminal numeric refusal from any wrapped size evidence; the served target preserves the actual-model header. */ export declare const gatewayRequestTooLargeError: (error: unknown, target?: ResolvedTarget) => GatewayError | undefined; /** Map a gateway condition to a provider-shaped error for the given wire (spec §3b). */ export declare const notImplemented: (wire: GatewayWire) => ProviderShapedError; //# sourceMappingURL=errors.d.ts.map