API
错误
分别处理认证、策略、限流与供应商故障
Octoryn 使用 HTTP 状态码与 JSON Error Body。错误可能位于顶层或 detail 下；稳健客户端应兼容两者，并避免把原始诊断暴露给最终用户。
错误形态
以 HTTP Status 作为首要分类。推理故障使用有界的顶层 error 对象；身份与请求依赖故障可能使用 FastAPI detail Envelope。
{
"error": {
"code": "routing_exhausted",
"message": "Provider temporarily unavailable",
"metadata": {
"error_type": "provider_unavailable",
"retry_after_seconds": 18
}
}
}状态码
按错误类别明确处理。
- 401 — Bearer 凭据缺失或无效
- 402 — 配置的预算 Authority 拒绝累计支出
- 403 — 租户、产品、策略、Scope 或其他 Admission 被拒绝
- 404 — 目录记录不存在
- 422 — Request body 验证失败
- 429 — 服务 Quota 超限或所有合资格供应商都被限流
- 502 — 不可重试的上游供应商故障
- 503 — 路由或必要 Authority 不可用
供应商与上游错误
策略路由可能先尝试合资格 Fallback，再返回标准化错误。供应商 Body、URL、部署标识和凭据都不能进入公开响应。
{
"error": {
"code": "routing_exhausted",
"message": "Provider temporarily unavailable",
"metadata": {"error_type": "provider_unavailable"}
}
}重试指引
只重试可安全重复的请求。使用带 Jitter 的指数退避，存在时遵守标准化 Retry-After Header，并限制总尝试次数。
- 不要原样重试 401、402、403、404 或 422
- 429 在指定延迟后重试
- 502 不可重试；明确为暂时性的 503 只能在严格 Attempt Budget 内重试
- 中断的 Stream 是部分输出
运营日志
记录时间、环境、路由、HTTP Status、安全错误码与请求关联标识；绝不记录 Bearer Token、供应商 Secret 或未经处理的敏感内容。