错误处理

本文档基于当前网关（gateway）与鉴权服务（passport）实现整理，重点覆盖 OpenAPI（/v1/openapi/*）接入时最常见的错误。

错误响应形式

鉴权失败时，网关通常直接返回 HTTP 状态码 + 文本错误信息（http.Error），例如：

HTTP/1.1 401 Unauthorized
Content-Type: text/plain; charset=utf-8

invalid api key

业务接口本身可能返回 JSON 结构，具体以对应 API 文档为准。

OpenAPI 鉴权错误清单

HTTP 状态码	错误信息（示例）	触发条件	处理建议
401	缺少 API Key	未传 Authorization	添加 Authorization: Bearer sk_*
401	认证格式错误	Authorization 非 Bearer <token> 格式	检查是否遗漏 Bearer 前缀
401	invalid api key	API Key 不存在/已删除/非法	重新复制正确的 sk_*
401	api key disabled	API Key 被禁用	在管理端启用或新建 Key
401	api key expired	API Key 已过期	重新生成 Key
403	invalid path	请求路径不符合鉴权策略（应为 /v1/*）	检查网关地址与路径拼接
503	鉴权服务不可用	网关无法调用鉴权服务	稍后重试并联系平台排查
500	鉴权服务初始化失败	网关鉴权配置或连接初始化异常	联系平台排查网关配置

重试建议

• 401/403：通常是鉴权或请求路径问题，不建议盲目重试，应先检查 API Key、请求头和网关地址。
• 500/503：可按指数退避重试（如 1s、2s、4s，最多 3 次）。
• 若持续出现 503，请附带请求时间、路径和请求追踪 ID 联系平台支持定位。