错误处理

错误响应通常包含 error.message，部分场景还包含 type、code 或请求标识。客户端应同时记录 HTTP 状态码和安全脱敏后的响应正文。

状态码	常见原因	建议
400	JSON、参数、消息结构或模型能力不兼容	检查请求体，移除不支持的可选字段。
401	缺少、错误、失效或已删除的令牌	检查 Bearer Header，在控制台轮换令牌。
403	令牌分组、模型或接口权限不足	确认令牌范围并联系账号提供者。
404	路径错误或资源不存在	确认 Base URL 包含 /v1 且端点拼写正确。
429	额度不足、频率限制或并发限制	查看余额与日志，按 Retry-After 或指数退避重试。
500	网关内部错误	保存时间和请求标识，稍后重试。
502/503	上游不可用、渠道异常或无可用节点	使用退避并限制总重试次数。
504	上游处理超时	缩短请求、提高客户端超时或稍后重试。

推荐重试策略

• 网络失败、429、502、503、504：使用带随机抖动的指数退避，最多重试 2–3 次。
• 400、401、403、404：修正配置或请求后再发送，不要自动循环重试。
• 流式请求中断：先判断是否已产生输出，再决定是否重新发起，避免重复内容和重复计费。
• 日志中不得打印完整 API Key、管理员凭据或敏感提示词。

排查顺序

1. 用同一令牌请求 /v1/models。
2. 使用最小请求体和文档中的已验证模型重试。
3. 查看控制台调用日志和额度。
4. 记录发生时间、端点、模型、HTTP 状态码和请求标识。
5. 按邀请渠道联系账号提供者；不要发送完整令牌。