Error Flow

Error Flow

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

Typed error

IngressError / RequestError / TranslationError / StreamTranslationError / application errors

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
JsonPayloadError	Shared core JSON path, pretty source location, and deserialization source details.
IngressError	Carrier-independent structured request normalization and validation failures.
RequestError	Application HTTP body/path failures and transparent wrapping of IngressError.
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	Non-streaming protocol payload conversion failures.
StreamTranslationError	Structured stream conversion and lifecycle semantic failures.
SseError	Application SSE carrier parsing failures.
ByteStreamError	Byte stream carrier failures.

Error versus observation

Core operations return typed errors when processing cannot continue. Legal adaptations and representational loss emit typed Observation values through Observer. Core must not both emit an observation and return the same failure; the application boundary observes, diagnoses, and renders a returned error once with HTTP/SSE context.

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
Shared core JSON error details	crates/proxai-core/src/error.rs
Core ingress errors	crates/proxai-core/src/ingress/error.rs
Core translation errors	crates/proxai-core/src/translation/error.rs and translation/stream.rs
Application error composition and rendering	src/error/
SSE carrier failures	src/sse.rs and src/sse_translation.rs
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