错误码与错误处理

无界模型云（Wujie Model Cloud）所有 /v1/* 接口的错误都以结构化 JSON 返回，便于客户端解析与分支处理，不会用裸的连接重置代替错误体。

私有化部署的错误结构与错误码一致 → 企业私有化部署。

错误响应结构

OpenAI 兼容接口（/v1/chat/completions、/v1/images/* 等）：

{
  "error": {
    "message": "人类可读的错误描述",
    "type": "invalid_request_error",
    "code": "optional_machine_code"
  }
}

Anthropic 原生接口（/v1/messages）在此基础上额外携带顶层 type: 'error'：

{
  "error": {
    "message": "人类可读的错误描述",
    "type": "invalid_request_error"
  },
  "type": "error"
}

• message：人类可读描述，可直接展示给开发者（不建议直接展示给终端用户）。
• type：错误类型。限流为 rate_limit_exceeded，参数 / 路由类错误为 invalid_request_error，鉴权类见下表。
• code：部分错误带稳定的机器码（如计价缺失防御闸、未捕获异常兜底），用于精确分支判断。

鉴权错误

鉴权在请求进入业务路由前统一校验。API Key 必须以 Authorization: Bearer gk_... 形式传入（带 Bearer 方案前缀，裸 gk_... 会被拒绝）。

数据面鉴权错误是扁平结构——顶层 error 即错误码，message 是描述（与下文业务错误的嵌套 { error: { type, message } } 不同）：

{
  "error": "missing_api_key",
  "message": "API key required (Authorization: Bearer gk_...)"
}

对话三件套（/v1/chat/completions、/v1/messages、/v1/responses）在数据面要求 ai:chat scope；缺少时返回 403 insufficient_scope。详见 鉴权与 API Key。

路由错误

LLM 接口需要确定目标 provider（通过 ?provider=X、body.provider、或 X-Provider 头指定；Anthropic 原生 /v1/messages 默认 provider 为 anthropic）。

{
  "error": {
    "message": "'provider' is required: pass it via ?provider=X or body.provider (valid: anthropic, dashscope, deepseek, ...)",
    "type": "invalid_request_error"
  }
}

限流错误（429）

超过速率 / 配额限制返回 429，type 为 rate_limit_exceeded，并在响应头 retry-after 给出建议等待秒数。

{
  "error": {
    "message": "rate limit exceeded",
    "type": "rate_limit_exceeded"
  }
}

HTTP/1.1 429 Too Many Requests
retry-after: 12
content-type: application/json

限流维度与退避建议见 限流与配额。

计价缺失防御闸（402）

当某模型对当前组织缺少有效计价信息时，网关主动拒绝该请求而非按 0 计费，返回 402，type 为 billing_error，并附稳定机器码 MISSING_MULTI_CURRENCY_PRICE。遇到该错误说明模型计价未确认，请联系客服 / 管理员补全组织价格，再重试。

{
  "error": {
    "message": "模型计价信息未确认,请联系客服处理",
    "type": "billing_error",
    "code": "MISSING_MULTI_CURRENCY_PRICE"
  }
}

未捕获异常兜底（503）

任何未被业务逻辑捕获的内部异常都会被网关兜底为带 JSON 体的 503（机器码 handler_unhandled_exception），而不是连接重置 / 协议中断——客户端始终能解析到一个错误体。

{
  "error": {
    "code": "handler_unhandled_exception",
    "message": "internal handler error: <detail>",
    "type": "Error"
  }
}

遇到 503 handler_unhandled_exception 属于网关侧瞬时故障，可做有限次重试。

重试建议

• 429：读取 retry-after 头退避后重试，不要无退避反复重试。详见 限流与配额。
• 瞬时 5xx（如 503、网络抖动）：做有限次重试（建议 ≤ 3 次，指数退避），避免拉长整体超时。
• 400 / 401 / 403 / 402：属于请求侧问题（参数、鉴权、授权、计价），重试无意义，应修正后再发。