错误与调试

RouteAPI 会尽量返回统一的错误结构，帮助客户端判断错误来源和处理方式。

标准错误结构

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

常见状态码

状态码	类型	常见原因	建议处理
400	请求错误	参数格式错误、模型不支持参数	检查请求体和模型能力
401	认证错误	Token 缺失、错误或已删除	检查 Authorization
402	余额错误	用户余额不足或 Token 额度耗尽	充值或调整额度
404	路径错误	Endpoint 不存在	检查 URL
429	限流	用户、Token 或系统限流	降低并发或调整限流
500	系统错误	RouteAPI 内部错误	查看服务日志

排查顺序

1. 确认请求 URL、Token 和模型 ID。
2. 确认 Token 所属用户余额、额度和访问权限。
3. 查看控制台使用日志，确认请求是否进入 RouteAPI。
4. 如果是流式请求，确认客户端是否正确处理 SSE。

服务侧错误与本地错误

RouteAPI 是网关系统，错误可能来自三层：

层级	示例
客户端	请求体 JSON 错误、Token 缺失
RouteAPI	余额不足、无权限
模型服务	服务限流、服务不可用、模型下线

生产排障时建议同时记录：

• 请求时间
• Token 或用户 ID
• 模型 ID
• HTTP 状态码
• RouteAPI 返回的错误 code
• 控制台使用日志中的错误信息