Error Flow

Error Flow

This page explains how internal failures become compact client-facing HTTP or SSE errors.

Internal error

RequestError / ConfigError / UpstreamError / TranslationError / SseError / ByteStreamError

Classify

Select stable client-facing error type and status

Preserve safe details

Keep useful upstream headers without leaking private data

Render

HTTP body or SSE error event depending on response state

Client error

text or JSON ErrorResponseSpec

Internal taxonomy

Error family	Use for
RequestError	Inbound body parsing and client request validation failures.
ConfigError	Config loading, config-file reads, route/provider validation, and startup config failures.
InternalError	Proxy runtime invariants, local filesystem IO, body reads, serialization, and boundary failures.
UpstreamError	Provider send failures, non-success statuses, and upstream body-read failures.
TranslationError	Protocol payload conversion failures.
SseError / SseTranslationError	SSE event semantics and streaming conversion failures.
ByteStreamError	Byte stream carrier failures.

Projection rules

Rule	Reason
Do not expose internal taxonomy verbatim	Client-facing types should be stable and compact.
Always include numeric status in payload	SSE error events cannot change HTTP status after streaming starts.
Preserve useful upstream diagnostic headers when present	Retry-After, upstream request ids, and rate-limit headers help debugging.
Do not fabricate upstream code or param	Those values only exist when the upstream provided them.
Do not log private request bodies or Authorization headers	Errors must remain privacy-safe by default.

HTTP vs SSE

Carrier	Behavior
HTTP before response starts	Render normal HTTP error with configured text or JSON payload.
SSE after stream starts	Render protocol-compatible error event where possible; include payload status.
Upstream non-2xx	Project upstream failure into configured client-facing error format and safe preserved headers.
Stream semantic failure	Emit/return an error that distinguishes incomplete terminal semantics from normal completion.

Do not wrap semantic stream failures as IO

Use stream-specific errors for SSE semantics and byte-stream carrier errors. Reserve std::io::Error for real OS/filesystem IO.

Source owners

Concern	Owner
Domain error taxonomy	src/error/
SSE semantic failures	src/sse.rs and streaming translation modules
Byte stream carriers	src/http_support/
Proxy request lifecycle	src/lib.rs and pipeline modules

Related docs

• Error Handling Internals
• Error Responses
• Behavior Contracts
• Streaming Internals