黑马天启 · 多模型 Token 平台

错误码与限流

平台所有错误都遵循同一套约定：HTTP 状态码 + 机器可读的 error.code + 可追踪的 request id。 本文是汇总入口，逐条细节见下方各页。

错误码总表

错误码 HTTP 触发条件
invalid_token 401 API Key 拼写错误、已删除或已禁用
no_access_to_model 403 该 Key 的模型白名单里没有这个模型，或模型未对外开放
realname_required 403 调用了「需要实名」的模型（图像/视觉类）但账号未实名
temp_blacklisted 403 来源 IP 或账号被平台临时限制
channel_capacity_exceeded 429 目标渠道达到 RPM/TPM/并发上限
rate_limited 429 触发平台的请求频率限制
invalid_parameter_error 400 请求体字段类型/取值不合法
model_not_found 404 模型名不存在或未开放
AUTH_SESSION_LIMIT 409 单账号活跃会话数超过上限
AUTH_SESSION_ISSUANCE_LIMIT 429 时间窗内签发的会话数超过上限
INVOICE_SERVICE_UNAVAILABLE 502 开票服务暂时不可用
INVALID_INVOICE_ID 400 发票申请 id 不合法
SUPPLIER_UNAVAILABLE 502 供应商服务暂时不可用
UPSTREAM_MODELS_FAILED 502 拉取上游模型清单失败（渠道不可达或密钥无效）
ATTACHMENT_UNAVAILABLE 404 附件不存在或无权查看
ROUTE_POLICY_FAILED 500 智能路由策略读写失败
AUTH_INSUFFICIENT_PRIVILEGE 403 当前角色没有该操作权限
upstream_error 502 上游返回 5xx 或连接失败

通用处理原则

  1. 先看 error.code，不要只按 HTTP 状态码分支——同一 403 可能是权限、实名或临时限制；
  2. 保留 request id：报障与对账都以它为准；
  3. 区分退避与重试：
    • rate_limited / channel_capacity_exceeded → 指数退避 + 抖动后重试，或切备用模型；
    • invalid_token / no_access_to_model / invalid_parameter_error → 先改代码，重试无用；
    • upstream_error / upstream_models_failed → 有限重试，超阈值切备用渠道；
  4. 被拒绝的请求不计费，平台在入口或选路后即返回，不会产生上游费用。

限流的三个层次

层次 说明 触发后的表现
模型 RPM 单个模型在窗口内的请求数上限 rate_limited
渠道容量 上游渠道的并发/配额已满 channel_capacity_exceeded
临时黑名单 来源 IP 或账号被风控临时限制 temp_blacklisted

逐条错误码

相关