错误处理

调用 API 时遇到报错？本页列出常见错误码的含义、原因与排查建议。大多数情况下，错误响应中的 message 字段会直接说明原因，建议优先查看。

常见错误码

错误码	含义	常见原因与处理建议
400	请求参数错误	参数不合法，请参考报错信息（message）修正请求参数
401	未授权	API Key 未设置或不正确，请检查请求头 Authorization: Bearer API_KEY 是否填写完整
403	禁止访问	账户余额不足或权限不够。权限不够最常见的原因是该模型要求完成实名认证，其他情况请参考报错信息
404	任务不存在	查询或续接异步任务（如延长、重混）时，传入的任务 ID 不存在、已过期或不属于当前账号，报错信息中会带上该 ID
429	触发限流	触发了速率限制，请参考 message 判断触发的是 RPM / TPM 中的哪一种，详见速率限制；也可能是参数错误导致请求反复重试，最终触发限速
500	服务器内部错误	服务发生未知错误，请记录 Request ID 并联系客服排查
503 / 504	服务暂时不可用	一般是系统负载较高，稍后重试即可；对话类请求可尝试开启流式输出（"stream": true）降低超时概率

如何读懂错误响应

错误响应通常为 JSON 格式，包含错误码、错误信息与请求 ID：

{
  "error": {
    "code": "insufficient_quota",
    "message": "账户余额不足，请充值后重试 (request id: 202511162255194339355347BE3UyUY)",
    "type": "api_error"
  }
}

• message：最直接的问题描述，优先阅读
• code / type：可用于程序化的错误分类处理
• Request ID：联系客服时提供该 ID，可大幅加快排查速度

重试建议

• 可重试的错误（429、500、503、504）：建议采用指数退避策略重试，例如等待 1s、2s、4s……最多重试 3~5 次
• 不可重试的错误（400、401、403、404）：请先修正参数、密钥或权限问题，盲目重试只会浪费配额甚至触发限流
• 为客户端设置合理的超时时间，避免请求无限挂起

节点级自动重试

Calgine Tokens 的每个模型背后由多个提供商节点支撑。单个节点失败时，系统会自动切换节点重试，全程对您的代码透明。详见提供商与路由。

仍然无法解决？

请携带以下信息联系客服：

• 完整的错误响应（含 message）
• Request ID
• 使用的模型与请求时间