接入与帮助HTTP

错误处理

常见状态码与处理方法

常见状态码

参数	类型	说明
`400`	请求错误	检查 JSON、必填参数与参数类型
`401`	鉴权失败	确认使用有效 API Key，并带上正确的鉴权头
`404`	路径或模型不存在	检查 Base URL、接口路径与完整模型 ID
`429`	限流或额度不足	读取错误消息与 Retry-After，降低并发后重试
`500`	服务错误	记录响应实际返回的请求 ID，稍后重试；持续出现时联系支持
`502 / 503`	服务暂时不可用	采用指数退避后重试，或选择同类模型

协议	错误字段	请求 ID
OpenAI 兼容接口	`error.type / error.code / error.message`	`x-request-id 响应头`
Anthropic Messages	`type: error + error.type / error.message`	`request-id 响应头或正文 request_id`
Gemini Generate Content	`error.code / error.status / error.message`	仅记录响应实际返回的请求标识

OpenAI 兼容接口

{
  "error": {
    "message": "参数格式不正确",
    "type": "invalid_request_error",
    "param": "model",
    "code": "invalid_model"
  }
}

Anthropic Messages

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "参数格式不正确"
  },
  "request_id": "req_01JY7X"
}

Gemini Generate Content

{
  "error": {
    "code": 400,
    "message": "参数格式不正确",
    "status": "INVALID_ARGUMENT"
  }
}

OpenAI 兼容接口读取 x-request-id，Anthropic Messages 读取 request-id 或错误正文中的 request_id。字段或响应头不存在时不要自行生成；联系支持时同时提供请求时间、接口、模型与完整错误正文，不要发送 API Key。