开放接口错误状态码

开放接口的错误状态码主要包括 HTTP 状态码和错误信息两部分。HTTP 状态码用于指示请求的总体结果，而错误信息则提供了更具体的错误细节。

一、HTTP 状态码

状态码	含义（简要）	Open 侧典型场景
401	令牌无效	缺 token、令牌无效
403	禁止访问	客户端 IP 不在第三方白名单
422	请求体验证失败	请求体不合法
429	请求过于频繁	限流不通过

---

二、错误信息

字段	典型 JSON 结构
detail	{"detail": "<字符串>"} 或 {"detail": [ ... ]}

---

三、完整 HTTP 回复示例

1. 401 — 缺少 access_token

HTTP/1.1 401 Unauthorized
date: Mon, 28 Apr 2026 12:00:00 GMT
content-type: application/json
content-length: 38

{"detail":"缺少 access_token"}

2. 401 — 无效的令牌

HTTP/1.1 401 Unauthorized
content-type: application/json

{"detail":"无效的令牌"}

3. 403 — IP 不在白名单

HTTP/1.1 403 Forbidden
content-type: application/json

{"detail":"IP 203.0.113.10 不在白名单中"}

4. 429 — 第三方限流

限流策略详见 速率限制。

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

{"detail":"请求过于频繁，超过应用的每分钟次数限制"}

---

四、422 — 请求体校验失败

当请求体缺少必填字段或字段类型不正确时，Open 会返回 422 状态码，并在 detail 字段中提供具体的错误信息。

HTTP/1.1 422 Unprocessable Entity
content-type: application/json

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "model"],
      "msg": "Field required",
      "input": {
        "messages": [{"role": "user", "content": "hi"}]
      }
    }
  ]
}