错误流程

错误流程

本页说明内部失败如何变成紧凑的客户端 HTTP 或 SSE 错误。

Typed error

IngressError / RequestError / TranslationError / StreamTranslationError / 应用错误

分类

选择稳定的客户端错误 type 和 status

保留安全细节

保留有用上游 headers，同时不泄漏私有数据

渲染

根据响应是否已开始，渲染 HTTP body 或 SSE error event

客户端错误

text 或 JSON ErrorResponseSpec

内部分类

错误族	用于
JsonPayloadError	Core 共享的 JSON path、pretty source 位置和反序列化 source 详情。
IngressError	与 carrier 无关的结构化请求归一化和校验失败。
RequestError	应用层 HTTP body/path 失败，以及对 IngressError 的透明包装。
ConfigError	配置加载、配置文件读取、route/provider 校验和启动配置失败。
InternalError	代理运行时不变量、本地文件系统 IO、body 读取、序列化和边界失败。
UpstreamError	Provider 发送失败、非成功状态和上游 body 读取失败。
TranslationError	非流式协议 payload 转换失败。
StreamTranslationError	结构化 stream 转换和 lifecycle 语义失败。
SseError	应用层 SSE carrier 解析失败。
ByteStreamError	Byte stream carrier 失败。

Error 与 observation

Core 操作无法继续时返回 typed error；合法适配或目标协议无法表达的损失通过 Observer 发出 typed Observation。Core 不应对同一个失败既发 observation 又返回 error；应用边界结合 HTTP/SSE context，只观测、诊断和渲染一次返回的错误。

投影规则

规则	原因
不要逐字暴露内部 taxonomy	客户端 type 应稳定且紧凑。
Payload 总是包含数字 status	SSE error event 在 stream 开始后无法再改变 HTTP status。
上游提供时保留有用诊断 headers	Retry-After、upstream request id 和 rate-limit headers 有助于调试。
不要伪造上游 code 或 param	这些值只有上游实际提供时才存在。
不要记录私有 request body 或 Authorization headers	错误默认也必须隐私安全。

HTTP 与 SSE

Carrier	行为
HTTP 响应开始前	按配置渲染普通 HTTP error，payload 为 text 或 JSON。
SSE stream 开始后	尽可能渲染协议兼容 error event；payload 中包含 status。
上游非 2xx	投影为配置的客户端错误格式，并保留安全 headers。
Stream 语义失败	返回/发出能区分 incomplete terminal semantics 与正常完成的错误。

不要把语义性流失败包装成 IO

SSE 语义和 byte-stream carrier 错误应使用 stream-specific errors。std::io::Error 只用于真实 OS/文件系统 IO。

源码归属

关注点	归属
Core 共享 JSON 错误详情	crates/proxai-core/src/error.rs
Core ingress 错误	crates/proxai-core/src/ingress/error.rs
Core translation 错误	crates/proxai-core/src/translation/error.rs 与 translation/stream.rs
应用错误组合与渲染	src/error/
SSE carrier 失败	src/sse.rs 与 src/sse_translation.rs
Byte stream carriers	src/http_support/
Proxy 请求生命周期	src/lib.rs 和 pipeline modules

相关文档

• 错误处理内部实现
• 错误响应
• 行为契约
• 流式内部实现