CloudRouter 文档

简体中文

English

简体中文

English

Appearance

错误码与排障 ​

适用角色：开发者 更新日期：2026-07-02

本文说明 CloudRouter 返回的各类错误码含义、如何区分"是谁的问题"、以及推荐的重试与超时策略。

一、错误码速查 ​

HTTP 码错误代码含义你该做什么
400invalid_request_error请求参数非法检查请求体格式、参数
401authentication_errorAPI Key 无效或缺失检查 Authorization: Bearer 头
403余额/额度类（见下方说明）账户余额不足或额度封顶联系所属组织充值 / 上调额度
403Key 已过期API Key 过期联系组织重新分发 Key
429API_KEY_RATE_{5H,1D,7D}_EXCEEDEDKey 的限额耗尽（5h / 1d / 7d 窗口）等限额窗口重置或调高额度
429配额 / 并发类（见下方说明）Key 配额耗尽或并发超限等窗口重置 / 降低并发 / 联系组织调配额
502upstream_error模型供应商返回 5xx，统一映射稍后重试
500internal_server_errorCloudRouter 平台自身故障联系技术支持

⚠️ 关于 403/429 的具体错误代码字符串：组织余额耗尽、子用户额度用尽、Key 配额耗尽、并发超限等场景各自的 error code，请以接口实际返回的 code 字段为准，不要硬编码这些字符串做精确匹配。可靠的做法是按 HTTP 状态码分类：余额/额度封顶为 403，限额/限流/并发为 429。API_KEY_RATE_{5H,1D,7D}_EXCEEDED 三个限额码已确认稳定，可放心使用。

关于 429 细分：限额耗尽按时间窗口返回 API_KEY_RATE_5H_EXCEEDED / API_KEY_RATE_1D_EXCEEDED / API_KEY_RATE_7D_EXCEEDED，等窗口重置即可；配额耗尽 / 并发超限需调整配额或降低并发。

关键设计 1：模型供应商的 5xx 统一映射为 CloudRouter 的 502；只有 CloudRouter 平台自身故障才返回 500。

关键设计 2：注意区分 403 余额不足 和 429 限额/限流——前者是"没钱了"（充值解决），后者是"触发了额度/频率限制"（等窗口重置或调配额）。两者处理方式完全不同。

⚠️ 带指纹调用的特殊报错：指纹是平台为每个分组自动分配的短标识符，固定不变，你可以在「调用指南」页面查看。用带指纹的调用名点名分组时，若该分组不在你账户的可用范围内、或对应渠道不可用，平台直接返回错误，不自动切换、不降级、不兜底。请在客户端做好重试或改用可用分组，机制见 调用指南与双路由。

二、错误响应体格式 ​

CloudRouter 的错误响应体有多种形态，做错误解析时需要同时兼容。

形态 A：API 网关校验类（error 对象嵌套结构） ​

400 参数错误、401 认证失败、502 模型供应商故障等由 API 网关返回，错误信息在 error 对象里。注意：是否带最外层 type: "error" 取决于命中的是 Anthropic 兼容端点还是 OpenAI 兼容端点——同一端点、不同分组，外层结构会不同：

json
// Anthropic 兼容端点（如走 Anthropic 系分组）
{
  "type": "error",
  "error": { "type": "upstream_error", "message": "Upstream service temporarily unavailable" }
}

// OpenAI 兼容端点（如走 OpenAI 系分组）—— 没有最外层 type
{
  "error": { "type": "invalid_request_error", "message": "..." }
}

解析建议：统一读 error.type 与 error.message，不要依赖最外层 type 字段是否存在。两种端点的 error 对象内字段一致。

常见 error.type 取值：

error.type对应场景
invalid_request_error400 参数错误
authentication_error401 认证失败
upstream_error502 模型供应商故障

形态 B：认证 / 计费 / 限额类（顶层 code / message 结构） ​

最高频的 403 余额/额度、429 限额/配额等业务错误采用不同结构——错误代码在顶层 code 字段（字符串），没有外层 type/error 包裹：

json
{
  "code": "API_KEY_RATE_5H_EXCEEDED",
  "message": "rate limit exceeded"
}

形态 C：500 平台内部故障 ​

json
{
  "code": 500,
  "reason": "internal_server_error",
  "message": "internal error"
}

⚠️ 解析提醒：做精细化错误处理时，不要只读 error.type——余额不足、限额、配额这类最常见的 4xx 业务错误，错误代码在顶层 code 字段（形态 B），而非 error.type（形态 A）。建议同时兼容顶层 code 与 error.type 两个字段；500 则是 code（整数）+ reason。具体字段以接口实际返回为准。

三、判断"这是谁的问题" ​

收到错误后，按 HTTP 状态码判断方向：

  • 4xx — 请求本身有问题（参数错误、认证失败、余额不足、限额超限）。检查请求内容。如果带指纹却报"分组不可达"，说明该分组不在可用范围或当前不可用（不会自动降级），请改用可用分组或联系平台。
  • 500 — CloudRouter 平台自身故障，请联系客服支持。
  • 502 — 模型供应商侧故障（供应商返回 5xx 统一映射为 502），请稍后重试。

不确定是 CloudRouter 还是模型供应商故障时，先确认错误码：502 指向模型供应商，500 指向平台自身。

四、推荐的重试策略 ​

python
import time
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.cloudrouter.online/v1")

def chat_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="claude-sonnet-4-6",
                messages=messages,
                timeout=60
            )
        except Exception as e:
            status = getattr(e, "status_code", None)
            # 4xx 客户端错误不重试（重试也没用）
            if status and 400 <= status < 500 and status != 429:
                raise
            # 429/502/500 指数退避重试
            if attempt < max_retries - 1:
                wait = 2 ** attempt   # 1s, 2s, 4s
                time.sleep(wait)
            else:
                raise

原则：

  • 4xx（除 429）不重试——参数/认证/余额/Key 过期、带指纹分组不可达等问题，重试无意义；需按错误类型处理（检查参数、联系组织充值或重发 Key、改用可用分组等）
  • 429 / 502 / 500 才重试——用指数退避（1s→2s→4s），避免过多请求
  • 设置 timeout——建议 60s，避免请求无限挂起
  • 限制最大重试次数——通常 3 次，避免无限重试

五、流式（SSE）场景的特殊处理 ​

流式请求中途出错时，你会先收到部分内容块，然后收到一个 error 事件：

text
data: {"choices":[{"delta":{"content":"前半段内容"}}]}
data: {"type":"error","error":{"type":"upstream_error","message":"..."}}

随后连接断开。处理建议：

  • 在 SSE 解析逻辑中单独识别 error 事件，不要当成正常内容
  • 客户端已渲染的"半截内容"需要业务层决定如何处理（清除/标注中断/允许重新生成）
  • 这是流式调用最易踩坑的场景，建议封装统一的流式错误处理

六、找技术支持时提供什么 ​

联系 CloudRouter 支持时，附上以下信息可加快定位：

  • 出错的时间点（精确到分钟、含时区）
  • 调用的模型调用名（裸名或带指纹）和端点
  • HTTP 状态码和完整错误响应体
  • 是否流式（stream）
  • 大致调用频率（帮助判断是否限流）

联系我们 ​

  • 电子邮箱：support_cloudrouter@clouditera.com
  • QQ 社群：712273971
  • 平台网址：cloudrouter.online