错误码

SmartAPI 返回标准 HTTP 状态码。错误响应体遵循所调用接口的格式：/chat/completions 与 /responses 为 OpenAI 风格，/messages 为 Anthropic 风格。

每个响应——包括错误——都包含 X-Request-Id 请求头。反馈问题时请附带该值，以便快速排查。

状态码#

HTTP	错误类型	触发场景
`400`	`invalid_request_error`	JSON 格式错误或缺少 `model` 字段。
`400`	`unsupported_protocol`	该模型不支持此接口/协议。
`401`	`invalid_api_key`	密钥缺失、格式错误、被禁用或已过期。
`402`	`insufficient_quota`	账户余额耗尽。
`404`	`model_not_found`	模型不存在或已下架。
`429`	`rate_limit_exceeded`	触发密钥限流或超出总配额。
`502`	`upstream_error`	模型服务返回错误；跨通道自动重试后仍失败。
`503`	`service_unavailable`	模型已上架，但当前无可用路由通道。
`504`	`upstream_timeout`	等待模型服务响应超时；跨通道自动重试后仍失败。
`500`	`internal_error`	内部未预期错误。

OpenAI 风格错误体#

由 /chat/completions 返回：

{
  "error": {
    "message": "Invalid, missing, disabled or expired API key.",
    "type": "invalid_api_key",
    "code": "invalid_api_key",
    "param": null
  }
}

Anthropic 风格错误体#

由 /messages 返回：

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid, missing, disabled or expired API key."
  }
}

错误处理建议#

401 / 402 —— 确认密钥已启用且账户余额为正。参见鉴权与计费。
404 / 400（unsupported_protocol） —— 核对模型标识，并确认调用了该模型对应的接口。参见模型。
429 —— 降低请求频率或提高密钥限额。参见限流与配额。
502 / 503 / 504 —— 多为模型服务或路由层面的临时故障。SmartAPI 会对可用通道自动重试；建议指数退避后再次发起请求。