常见错误

API 请求失败时，先看 HTTP 状态码，再看响应体里的错误信息。下面是最常见的处理方式。

401 Unauthorized

通常表示 API Key 缺失、格式错误或已失效。

请检查：

• Authorization 请求头是否为 Bearer YOUR_RETTERMAI_API_KEY。
• Key 是否来自 回端AI 控制台。
• Key 是否被删除或轮换。

402 Payment Required

通常表示余额不足或账户计费状态不可用。

请检查：

• 钱包余额是否足够。
• 充值订单是否已经入账。
• 余额明细里是否有最近的消费或调整记录。

403 Forbidden

通常表示账号、模型或上游权限不允许当前请求。

请检查：

• 模型名是否来自控制台「模型状态」页面。
• 账号是否有权限使用该模型或通道。
• 是否正在使用错误的区域 Endpoint。

404 Not Found

通常表示路径错误。OpenAI 兼容请求应使用：

https://api.ai.retterm.cn/v1/chat/completions

如果你使用 SDK，请确认 baseURL 是 https://api.ai.retterm.cn/v1，而不是完整的 /chat/completions 路径。

429 Too Many Requests

通常表示请求过快或上游限流。

建议：

• 降低并发。
• 增加请求间隔。
• 使用指数退避重试。
• 如果持续出现，请联系支持并提供模型名、时间和请求量级。

5xx

500、502、503、504 通常表示入口服务或上游模型临时异常。

建议：

• 短暂重试，并设置最大重试次数。
• 记录请求时间、Endpoint、模型名和错误响应。
• 查看控制台「模型状态」是否有可用性变化。
• 如果持续出现，请联系支持。

仍然无法解决

请把请求时间、Endpoint、模型名、HTTP 状态码和错误响应整理后，按 联系支持 的说明提交。