错误码与重试

错误码与重试

HTTP 状态码

状态码	含义	触发场景	调用方建议
400	请求错误	协议校验失败、请求体非法	修正请求，不重试
401	认证失败	API Key 缺失、无效或已失效	检查 Key，不重试
403	权限不足	Key 无权访问该模型 / 渠道	核对应用渠道授权，不重试
404	资源不存在	路径错误、模型未找到	核对端点路径，不重试
429	限流	触发令牌桶限流或上游限流	退避后重试
500	服务器错误	网关内部异常	稍后重试
502	上游错误	Provider 返回错误（含模型不存在，错误码为 MODEL_NOT_FOUND）	切换模型或稍后重试
503	熔断开启	端点熔断器处于 OPEN	稍后重试

错误响应格式

codingas.com 根据请求端点返回两种错误格式，调用方需分别处理。

OpenAI 兼容端点

POST /v1/chat/completions、GET /v1/models 的协议校验错误返回 OpenAI 标准格式：

{
  "error": {
    "message": "messages 字段不能为空",
    "type": "invalid_request_error",
    "code": "invalid_request"
  }
}

Anthropic 兼容端点

POST /anthropic/v1/messages 的协议校验错误返回 Anthropic 标准格式：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "messages 字段不能为空"
  }
}

拦截器短路错误（401 / 403 / 429）

认证、IP 黑名单、角色授权与限流在拦截器层短路，不经过上述协议格式，返回轻量 JSON：

状态码	响应体
401 认证失败	{"code": "UNAUTHORIZED", "message": "..."}
403 IP 黑名单 / 角色不足	{"code": "ACCESS_DENIED", "message": "..."}
429 限流	{"error": {"code": "RATE_LIMIT_EXCEEDED", "message": "请求过于频繁，请稍后重试"}}

服务端异常（400 参数非法 / 404 / 409 / 500 / 502 / 503）

熔断、上游错误、服务器内部错误等经全局异常处理器返回网关统一格式 ApiResponse：

{
  "success": false,
  "error": {
    "code": "UPSTREAM_ERROR",
    "message": "上游服务返回错误"
  },
  "traceId": "trace_1753900200000",
  "timestamp": "2026-08-31T10:30:00Z"
}

常见 code：400 为 VALIDATION_ERROR / BAD_REQUEST；404 为 NOT_FOUND；409 为 CONFLICT；500 为 INTERNAL_ERROR；502 为上游错误类型名（如 UPSTREAM_ERROR、MODEL_NOT_FOUND）；503 熔断为 UPSTREAM_ERROR。

数据面每次调用的真实 traceId（UUID）记录在调用日志与应用日志中；响应体 traceId 字段当前为占位实现，请以日志为准。详见 可观测性。

网关内部重试

网关在调用上游 Provider 时会根据错误类型自动重试，对调用方透明。调用方收到的是最终结果或最终错误，无需感知中间重试。

重试策略由 RetryExecutor 按错误类型选择：

错误类型（ProviderErrorType）	含义	策略
RATE_LIMIT_ERROR	上游限流	限流退避重试（最多 5 次，2s 起步指数递增、60s 封顶）
TIMEOUT_ERROR	上游超时	快速重试
SERVICE_UNAVAILABLE	上游不可用	固定间隔重试（3 次、间隔 5s）
UPSTREAM_ERROR	上游其他错误	指数退避重试（默认最多 3 次、1s 起步 ×2）
NETWORK_ERROR	网络异常	指数退避重试
UNKNOWN_ERROR	未分类错误	指数退避重试
QUOTA_EXCEEDED	上游额度耗尽	不重试，触发渠道级故障转移
AUTHENTICATION_ERROR	上游认证失败	不重试，触发渠道级故障转移
INVALID_REQUEST	请求非法	不重试，不转移
MODEL_NOT_FOUND	模型不存在	不重试，不转移（触发模型自动废弃检测）

重试参数可通过 gateway.retry.* 配置调整，见 配置项参考。

重试与故障转移的关系详见 容灾与高可用。

调用方重试建议

虽然网关内部已重试，但调用方仍建议对最终返回的错误做适度重试：

• 429：指数退避重试（如 1s / 2s / 4s），最多 3 次
• 503：熔断恢复需要时间，间隔 5–10s 后重试
• 502：可切换备选模型重试，或退避后重试
• 500：退避后重试 1–2 次，持续失败应反馈
• 400 / 401 / 403 / 404：不重试，修正请求或鉴权

import time
import requests

def call_with_retry(url, headers, payload, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.post(url, headers=headers, json=payload, timeout=60)
        if resp.status_code == 200:
            return resp.json()
        if resp.status_code in (400, 401, 403, 404):
            raise Exception(f"不可重试错误 {resp.status_code}: {resp.text}")
        if attempt < max_retries - 1:
            time.sleep(2 ** attempt)  # 指数退避: 1s, 2s, 4s
    raise Exception(f"重试 {max_retries} 次后仍失败: {resp.status_code}")

故障排查

遇到持续错误时，按以下顺序排查：

1. 401 / 403：核对 API Key 与应用渠道授权（调用方密钥管理、应用管理）
2. 404：核对端点路径，注意 Anthropic 端点为 /anthropic/v1/messages（非 /v1/messages）
3. 429：检查 Key 限流配置与上游限流
4. 502 / 503：查看控制台熔断器大盘与容灾事件（容灾与高可用）
5. 500：记录 traceId 并反馈

更多排查指引见 故障排查。