UOUODUO AI Gateway

Guides

错误处理

常见 HTTP 状态码、错误类型、余额和限流问题的处理建议。

UOUODUO Gateway 的错误响应尽量保持 OpenAI 兼容。

客户端应同时检查 HTTP 状态码和响应体里的错误对象。

生产环境建议记录 request ID、模型、状态码和错误类型，方便后续排查。

典型错误响应如下：

{
  "error": {
    "message": "The API key is invalid.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

不同上游可能返回额外字段。

如果字段不完全一致，优先按 HTTP 状态码和 `message` 做用户提示。

HTTP status	常见 code	含义	处理建议
400	invalid_request_error	请求体格式错误或参数不支持	检查 JSON、模型参数和 endpoint
401	invalid_api_key	API key 缺失、错误或已撤销	重新创建 key，确认 Authorization header
403	forbidden	当前账户或密钥无权限	检查项目、分组、模型权限
404	model_not_found	模型不存在或不可见	到 `/models` 或 `/v1/models` 确认模型 ID
408	timeout	请求超时	缩短输入、降低 max_tokens，或重试
409	conflict	请求状态冲突	避免重复提交同一任务
422	validation_error	字段类型合法但语义不合法	检查参数范围和多模态格式
429	rate_limit_exceeded	触发限流	使用退避重试，读取 Retry-After
500	server_error	网关或上游内部错误	带 request ID 重试或联系支持
502	upstream_error	上游返回异常	换模型或稍后重试
503	service_unavailable	上游暂不可用	稍后重试，查看状态页
504	gateway_timeout	上游响应超时	降低输出长度或切换模型

401 通常来自密钥问题。

请确认请求里包含：

Authorization: Bearer $UOUODUO_API_KEY

不要把 `sk-xxx...` 直接放进 URL query。

如果密钥是项目密钥，请确认项目没有被归档，密钥没有被撤销。

余额不足通常表现为 402、403 或带有 quota 相关 message 的错误。

处理步骤：

生产服务建议在调用失败时把余额不足错误单独分类，避免误判成系统故障。

429 表示当前账户、项目、密钥或上游模型触发限流。

常见维度包括请求数、输入 token、输出 token 和并发任务数。

客户端应使用指数退避：

const delay = Math.min(30_000, 500 * 2 ** attempt);
await new Promise((resolve) => setTimeout(resolve, delay));

如果响应里包含 `Retry-After`，优先使用该值。

400 和 422 最常见于以下情况：

排查时建议先用最小请求体复现，再逐步加回参数。

502、503 和 504 往往来自上游模型服务。

如果日志显示某个供应商连续失败，可以先切换到同能力模型。

如果业务必须使用固定模型，请在应用层设置短时间重试和降级文案。

流式请求可能在连接建立后中断。

客户端需要处理三类状态：

详见 `/docs/guides/streaming`。

建议至少记录以下字段：

日志不要记录完整 prompt，除非用户明确允许。

如果仍无法定位，把 request ID、时间、模型和错误响应提交给支持团队。