附录 C. 错误码与处理建议
完整版章节。内容按 2026.10 主线代码与运行环境界面核对；具体入口以当前许可、账号权限和交付环境为准。
下表为产品实际返回的常见错误。排查时先看 HTTP 状态码，再看响应体里的 code 与 reason。
| HTTP | code / reason | 含义 | 处理建议 |
|---|---|---|---|
| :-- | :-- | :-- | :-- |
| 401 | invalid_api_key / LLM_AUTH_FAILED | 凭据无效、已撤销或已过期 | 在「API 密钥管理」确认密钥状态与有效期；重新签发后更新调用方配置 |
| 403 | 权限或范围不足 | 调用方不在包含该模型的分组的可用范围内，或被流量规则拒绝 | 核对可用范围；请求详情「路由与改写 › 命中记录」会指明命中的规则 |
| 403 | CONTENT_POLICY_BLOCKED | 内容被内容检测规则拦截，message 为配置的回复话术 | 在规则详情的流量视图核对命中项；误报时调整规则或先改为「仅记录」观察（第 14.12 节） |
| 403 | CONTENT_SAFETY_UNAVAILABLE | 判断模型不可用，且规则的「判断模型不可用时」为「拒绝」 | 在「全局设置 › 默认模型」或规则画布中核对判断模型状态，必要时更换模型（第 14.3 节、第 14.9 节） |
| 403 | REQUEST_ORIGIN_REJECTED | 控制面写请求的来源被 CSRF 校验拒绝 | 从控制台页面正常操作；跨站或来源伪造的请求会被拒绝 |
| 404 | model_not_found | 请求的模型不属于该密钥可用的服务 | 核对模型名与密钥所属服务；确认该模型已加入服务并发布 |
| 404 | unsupported_model_endpoint | 请求的路径不是标准模型端点 | 使用标准端点；需要原样直通时改用「API 服务」 |
| 413 | 请求体超限 | 请求体超过规则设置的上限 | 缩小请求体，或由管理员调整「请求体上限」 |
| 429 | rate_limit_exceeded / TRAFFIC_RATE_LIMITED | 触发请求速率或并发限额 | 按响应里的 retry_delay_seconds 等待后重试；需要更高额度时调整限额 |
| 429 | TRAFFIC_CONCURRENCY_LIMITED | 并发数超过上限 | 降低并发，或提高并发上限 |
| 429 | TRAFFIC_QUEUE_TIMEOUT | 排队等待超时 | 降低并发；或把超限动作从「排队」改为「直接拒绝」以便快速失败 |
| 429 | provider_account_rate_limited | 账号池内所有账号都达到每分钟请求上限 | 按响应头 Retry-After 等待后重试；需要更高吞吐时提高账号的「每分钟请求上限」或增加账号 |
| 429 | insufficient_quota / POOL_EXHAUSTED | Token 或金额预算已用尽 | 等待周期重置或调整配额；额度 0 表示硬墙 |
| 503 | TRAFFIC_CIRCUIT_OPEN | 熔断已打开 | 等待熔断时长结束并观察半开探测；同时排查上游是否持续失败 |
| 503 | model_route_unavailable / MODEL_ROUTE_NOT_CONFIGURED | 没有可用的路由目标，或路由未配置 | 检查模型分组是否已发布、模型的上游或规则目标是否健康 |
| 503 | token_rate_limit_backend_unavailable | 限额的计数后端不可用 | 属平台侧问题，联系支持 |
| 504 | LLM_TIMEOUT | 上游超时 | 检查上游可用性与超时配置；响应头超时不会重放请求 |
| 502 | LLM_STREAM_INTERRUPTED | 流式响应中途被中断 | 客户端按中断处理；排查上游稳定性 |
| 400 | VALIDATION_FAILED / invalid_request | 请求结构不符合接口要求 | 按接口文档核对字段与类型；错误来自网关侧校验时不会转发到上游 |
注意：同一个 HTTP 状态码下 reason 不同，含义与处置完全不同。例如 429 里 TRAFFIC_RATE_LIMITED 是限流、POOL_EXHAUSTED 是额度耗尽。排障时不要只看状态码。
---