API
错误
分别处理认证、策略、限流与供应商故障
Octoryn 使用 HTTP 状态码与 JSON Error Body。错误可能位于顶层或 detail 下；稳健客户端应兼容两者，并避免把原始诊断暴露给最终用户。
错误形态
以 HTTP Status 作为首要分类，并使用 error/code 字段进行程序化处理。
{
"detail": {
"error": "rate_limited",
"code": "RATE_LIMITED",
"retry_after_s": 18
}
}状态码
按错误类别明确处理。
- 400 — 请求格式或 Channel 无效；修复请求后再发送
- 401 — API Key/JWT 缺失、无效或已撤销；Code 可能包括 BAD_API_KEY 或 BAD_JWT
- 403 — 已认证但 Scope 或策略不允许；MISSING_SCOPE 表示 Scope 不足
- 404 — 路由或资源不存在
- 422 — Request body 验证失败
- 429 — 工作区或路由限流；优先使用 retry_after_s
- 502/503/504 — 合资格上游或服务路径故障；可考虑有界重试
供应商与上游错误
供应商故障可能显示为 upstream_rate_limited 或 upstream_error。策略路由可能先尝试合资格 Fallback 再返回错误。
{
"detail": {
"error": "upstream_rate_limited",
"retry_after": 30
}
}重试指引
只重试可安全重复的请求。使用带 Jitter 的指数退避，遵守 retry_after_s，并限制总尝试次数。
- 不要原样重试 400、401、403 或 422
- 429 在指定延迟后重试
- 瞬时 502、503、504 只能在严格 Attempt Budget 内重试
- 中断的 Stream 是部分输出
运营日志
记录时间、环境、路由、HTTP Status、安全错误码与请求关联标识；绝不记录 Bearer Token、供应商 Secret 或未经处理的敏感内容。