错误码大全
所有常见错误码的触发原因和解决方案
在调用 VibeAPI 过程中，你可能会遇到以下错误码。本文整理了常见错误的触发原因和解决方案。
429 — Too Many Requests（请求频率超限）
错误示例： status_code=429, 您已达到请求数限制：1分钟内最多请求XXX次
触发原因：
Default 分组（Kiro 渠道）启用了动态 RPM（每分钟请求数）上限。当平台总并发过快、短时间内请求量过大时触发保护机制。
解决办法：
- 降低并发频率：在代码中加入请求延迟或重试机制
- 切换分组：高并发场景建议切换至 Ultra 分组，没有严格 RPM 限制
5xx — 服务端错误（500 / 502 / 504）
错误示例：
status_code=504, bad response status code 504（网关超时）status_code=502, Upstream service...（上游服务异常）status_code=500, Response stream timeout...（流式响应超时）
触发原因：
5xx 错误通常不是你的代码问题。原因是上游官方账号临时不可用，或跨国网络传输出现波动/拥堵。
解决办法：
- 代码级重试：遇到 5xx 时等待 1-3 秒后自动重试 1-2 次
- 联系客服：如果持续大面积出现 5xx，截图联系运营人员进行线路切换
400 — Invalid Request（无效请求）
错误示例： status_code=400, Invalid request
触发原因：
- 基础参数/格式错误：不支持的模型名称、JSON 格式损坏、缺少必填参数
- Tool Calling ID 不匹配（最常见）：多服务商轮询/混用导致
Tool Calling ID 不匹配详解
Tool Calling 至少需要两次请求才能跑完一轮：
- 请求 1：模型生成
tool_use_id - 请求 2：客户端带着
tool_use_id回传tool_result
这是一个强关联的有状态过程。如果两次请求走了不同的后端节点（如负载均衡轮询或 Fallback 回退），第二个节点不认识第一个节点生成的 ID，就会报 400。
解决办法：
- 代理层：将 Tool Calling 的模型设定为「固定单一渠道」，不要轮询
- 代码排查：确认 Tool Calling 流程中没有触发 Base URL 切换逻辑
- 清理缓存：新建空白对话测试，旧的
tool_use_id可能来自其他服务商
401 / 403 — Unauthorized / Forbidden（Key 无效）
触发原因：
- API Key 输入错误或已过期
- Key 的分组不包含请求的模型
- Key 额度已用完
解决办法：
- 检查 Key 是否正确复制（注意前后空格）
- 确认 Key 的分组包含你要用的模型
- 在控制台检查 Key 的剩余额度
网站/接口打不开
详见 备用线路。
开发者最佳实践
为了获得最稳定的体验，建议在代码中封装：
- 异常捕获（Try-Catch）
- 指数退避重试（Exponential Backoff）
这能帮你自动过滤掉 99% 的偶发性网络与限流报错。