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 internal error

RequestError, ConfigError, InternalError, UpstreamError, TranslationError, SSE errors

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
RequestError	Inbound body or validation failure
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	Protocol payload conversion failures
SseError / SseTranslationError	SSE event semantics
ByteStreamError	Stream carrier failures

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 only the human-readable message, which is the default for Zed readability.

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

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.