Error Handling Internals

Error Handling Internals

ProxAI keeps internal errors strongly typed, then projects them into compact client-facing HTTP or SSE errors. The projection boundary is centralized so provider, upstream, and translation code do not each invent their own response format.

Typed inside, stable outside

Internal errors preserve domain semantics for code and diagnostics. Client responses stay small, stable, and readable.

Error projection pipeline

Typed error

Core IngressError/TranslationError plus application RequestError/InternalError/UpstreamError

error/render.rs

Maps domain errors into ErrorResponseSpec

ErrorResponseFields

Shared HTTP/SSE status + payload fields

Client response

HTTP text/json response or SSE error event bytes

Internal error taxonomy

Error type	Meaning
JsonPayloadError	Shared core JSON path/location/source details
IngressError	Core structured request normalization or validation failure
RequestError	Application body/path failure or wrapped IngressError
ConfigError	Config loading and config-file reads
InternalError	Runtime invariants, local IO, JSON serialization, internal body reads
UpstreamError	Upstream send/status/body-read failures
TranslationError	Core non-streaming protocol payload conversion failures
StreamTranslationError	Core structured stream conversion and lifecycle semantics
SseError	Application SSE carrier parsing
ByteStreamError	Stream carrier failures

Core domain errors are returned through Result and transparently wrapped by application errors so their source chains remain intact. Non-fatal adaptations use Observation instead; do not emit and return the same failure twice.

Do not hide semantic stream or HTTP failures inside std::io::Error; reserve IO errors for real OS/filesystem IO.

Client-facing payload

JSON format wraps a compact error payload:

{

error:{
message:"quota exhausted",
type:"upstream_error",
code:"rate_limit_exceeded",
param:"input",
status:429
}

}

Text format returns the same compact error object as pretty-printed JSON with text/plain, which keeps raw clients readable while preserving upstream code and param details.

Preserved upstream details

For upstream non-2xx responses, ProxAI keeps useful details when the upstream actually provides them:

• Retry-After
• upstream request id headers
• rate-limit headers
• OpenAI-style code
• OpenAI-style param
• Anthropic error.type, normalized as the provider error code

proxai-core::provider::normalize_provider_error owns structured JSON error normalization. The application keeps HTTP status/headers, body bytes, empty/non-JSON handling, and client-facing rendering. It should not fabricate upstream code or param values. These rules implement Behavior Contract C15 and C18.

Related docs

ConfigurationChoose text or JSON error responses with [error_responses].ObservabilityCapture and logging boundaries for debugging failures safely.TroubleshootingUser-facing symptom cards and next checks.