AI API 故障排除
本页整理 LLMPool AI API 的常见错误、原因和处理方式。请先确认使用的是正确协议：
- OpenAI 兼容 Base URL：
https://api.benpay.ai/openai/v1 - Anthropic 兼容 Base URL：
https://api.benpay.ai/anthropic/v1
错误响应字段说明见错误响应。
如何阅读表格： 先根据 HTTP 状态码判断错误大类，再使用 OpenAI
error.code或 Anthropicerror.type确认具体处理方式。不要依赖message文本进行程序判断。
推荐排查顺序
- 记录 HTTP 状态码、请求路径和响应 Header 中的请求标识；不要记录密钥或完整请求正文。
- 即使 HTTP 为非
2xx，也先判断正文是否为目标端点的结构合法业务对象，例如带status: "failed"的 Response；否则再按协议解析错误 envelope。 - OpenAI 按 HTTP 与
error.code定位；Anthropic 按 HTTP 与error.type定位。message只供人工阅读。 - 根据下表决定修正请求、联系平台支持或有限重试。重试前先确认操作是否可以安全重放。
认证与访问
OpenAI error.code | Anthropic error.type | HTTP | 自动重试 | 原因 | 解决方案 |
|---|---|---|---|---|---|
invalid_api_key | authentication_error | 401 | 否 | API 密钥缺失、格式错误、无效、过期、停用、未绑定账户，或账户不可用 | 确认 Header 和 Base URL；在 Dashboard 的 API 密钥 页面检查状态，必要时创建新密钥 |
ip_not_allowed | authentication_error，并带 error.code=ip_not_allowed | 403 | 否 | 请求来源 IP 不在该 API 密钥的白名单中，或代理没有传递预期的客户端 IP | 检查 API 密钥 IP 白名单；确认出口 IP，以及反向代理的 X-Forwarded-For / X-Real-IP 配置 |
OpenAI 使用：
Authorization: Bearer YOUR_API_KEY
Anthropic 优先使用：
x-api-key: YOUR_API_KEY
Anthropic 也接受 Authorization: Bearer YOUR_API_KEY。如果同时提供两种 Header，系统优先使用 x-api-key。
余额与计费
OpenAI error.code | Anthropic error.type | HTTP | 自动重试 | 原因 | 解决方案 |
|---|---|---|---|---|---|
insufficient_wallets | invalid_request_error，无独立标识 | 402 | 否 | 可用钱包余额与订阅余额不足 | 前往 Dashboard 充值或联系组织负责人，余额到账后重新提交 |
meter_price_rules_error | 不适用 | 400 或 500 | 否 | 计量规则缺失或不完整时返回 400；读取计量规则失败时返回 500 | 更换可用模型，或联系平台支持处理计费配置；原样重试不会解决问题 |
请求与参数
OpenAI error.code | Anthropic error.type | HTTP | 自动重试 | 原因 | 解决方案 |
|---|---|---|---|---|---|
invalid_request | invalid_request_error | 400 | 否 | JSON、Content-Type 或框架解析失败 | 检查 JSON、Content-Type、字段类型和必填字段 |
invalid_request_error | invalid_request_error | 400 或 422 | 否 | 上游拒绝参数或字段组合 | 检查目标模型支持的参数和内容类型 |
missing_model | invalid_request_error，无独立标识 | 400 | 否 | 请求体没有 model，或模型名为空 | 使用 Models 页面展示的 Product ID 填写 model |
context_length_exceeded | invalid_request_error，无独立标识 | 400 | 否 | 输入和预期输出超过模型上下文窗口 | 缩短历史消息、附件内容或最大输出 Token，或选择上下文更长的模型 |
conversion_error | 不适用 | 400 | 否 | Chat Completions 请求无法转换为目标 Responses 请求 | 简化输入内容，移除不受支持的 Responses 字段或内容类型 |
request_too_large | request_too_large | 413 | 否 | 整个 HTTP 请求体超过服务限制 | 减少文本、图片或文件大小；不要将大型文件直接内嵌到请求中 |
method_not_allowed | invalid_request_error | 405 | 否 | 路径存在，但 HTTP 方法错误 | 按 API 文档改用正确的 GET、POST 或 DELETE 方法 |
not_found | not_found_error | 404 | 否 | API 路径或请求的通用资源不存在 | 检查 Base URL、版本路径和资源 ID |
上游返回的参数错误会被替换为安全、统一的说明，因此客户端不应依赖某家上游的原始错误文案。
模型与路由
OpenAI error.code | Anthropic error.type | HTTP | 自动重试 | 原因 | 解决方案 |
|---|---|---|---|---|---|
invalid_model | invalid_request_error，无独立标识 | 400 | 否 | 模型标识为空或格式不合法 | 从 Models 页面复制 Product ID，不要填写上游模型 fullname |
model_not_found | not_found_error | 404 | 否 | 找不到对应 Product | 检查拼写，并确认模型仍在 Models 页面可见 |
model_not_supported | invalid_request_error，无独立标识 | 400 | 否 | Product 不支持当前协议或能力，例如图像、音频、Batch 或 Responses | 选择支持当前操作的模型，或改用该模型支持的 API |
service_unavailable | overloaded_error | OpenAI 503 / Anthropic 529 | 是 | 找到了 Product，但当前没有可用的匹配模型或容量 | 退避重试，或从 Models 页面选择其他可用模型 |
模型出现在目录中只代表客户端可以发现它，不保证当前一定有可用推理容量；实际调用还需要 Product 可用并具有匹配的在线模型。
限流
OpenAI error.code | Anthropic error.type | HTTP | 自动重试 | 原因 | 解决方案 |
|---|---|---|---|---|---|
rate_limit_exceeded | rate_limit_error | 429 | 是 | 客户端 IP、API 密钥、平台或上游触发请求限流 | 遵循 Retry-After（如有），使用指数退避并降低并发 |
rate_limited | rate_limit_error | 429 | 是 | 当前模型的所有候选上游都处于限流状态 | 退避重试或切换模型；不要立即并发重放相同请求 |
推荐退避间隔可从约 1s 开始，每次翻倍并增加随机抖动，同时设置最大重试次数和总超时。
上游服务
OpenAI error.code | Anthropic error.type | HTTP | 自动重试 | 原因 | 解决方案 |
|---|---|---|---|---|---|
upstream_configuration_error | api_error | OpenAI 502 / Anthropic 500 | 否 | 上游拒绝凭证、模型映射错误或平台上游配置异常 | 联系平台支持；不要反复修改自己的 API 密钥 |
upstream_unavailable | api_error | 502 | 是 | 上游连接失败或暂时不可用 | 退避重试，必要时更换模型；持续出现时联系支持 |
upstream_timeout | api_error | 504 | 是 | 上游未在超时时间内响应 | 退避重试；对于长输入可尝试缩短上下文或减少预期输出 |
| 不适用 | overloaded_error | 529 | 是 | Anthropic 兼容上游过载 | 退避重试或更换模型 |
LLMPool 可能在多个候选上游之间重试。最终错误由故障类别确定，不应根据错误文案推断具体使用了哪家上游。
服务内部错误
OpenAI error.code | Anthropic error.type | HTTP | 自动重试 | 原因 | 解决方案 |
|---|---|---|---|---|---|
internal_error | api_error | 500 | 有限 | 数据库、映射、解密或其他内部处理失败；Anthropic api_error 也可能是上游配置问题 | 等待后少量重试；持续出现时停止重试并联系支持 |
file_service_error | 不适用 | 500 | 有限 | 图片或附件的内部文件处理失败 | 确认附件格式和大小后重试；持续出现时联系支持 |
response_conversion_error | 不适用 | 500 | 有限 | Chat Completions 上游响应无法转换为 Responses 对象 | 少量重试或更换模型；持续出现时联系支持 |
内部错误会隐藏实现细节。客户端不应期望从错误消息中获得数据库、上游地址或配置内容。
流式请求中断
如果流已经开始，HTTP 状态可能仍为 200，随后才收到 stream_error 或 Anthropic event: error。
处理方式：
- 立即结束当前流，不要把已收到的片段当作完整结果。
- 记录错误类型和本地请求时间，不要记录完整 API 密钥或敏感正文。
- 确认操作可以安全重试后，再使用退避策略重新发起请求。
- 连续发生时，尝试更换模型并联系支持。
不同流式 API 的事件结构见错误响应。
常见场景速查
一直返回 401
- 确认请求发送到 LLMPool 的 OpenAI 或 Anthropic Base URL，而不是 Dashboard 地址。
- 确认没有把 Admin Token 或 Tenant Access Token 当成 AI API 密钥。
- 重新复制密钥，检查首尾空格和 Header 格式。
- 在 Dashboard 检查密钥是否过期或停用。
404 模型不存在
- 从 Models 页面复制模型名称。
- 请求中使用 Product ID，不要使用供应商内部模型 fullname。
- 检查使用的协议和操作是否与模型能力匹配。
频繁返回 429
- 降低并发和每秒请求数。
- 合并客户端重试，避免多个实例同时立即重试。
- 遵循
Retry-After，并加入随机抖动。 - 如果只有一个模型持续受限，选择其他可用模型。
频繁返回 5xx 或 529
- 先进行有限次数的退避重试，并尝试其他模型。
- 记录发生时间、协议、请求路径、HTTP 状态、结构化错误类型/错误码和模型 Product ID。
- 持续出现或多个模型同时失败时联系支持。
联系支持
请提供：
- 发生时间和时区
- OpenAI 或 Anthropic 协议
- 请求路径和 HTTP 方法
- HTTP 状态码、
error.type和error.code（如果存在） - 使用的模型 Product ID
- 是否为流式请求，以及问题能否稳定复现
- 响应 Header 中的请求标识（如果存在）
不要提供完整 API 密钥、请求正文、GraphQL 文档与变量、文件内容或包含查询参数的完整 URL。