> For the complete documentation index, see [llms.txt](https://docs.infoway.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.infoway.io/getting-started/error-codes/http.md).

# HTTP错误码

HTTP API接口错误码说明

请区分两套数字：

1. **HTTP 状态码**：网关 / CDN 返回（`401` `404` `429` `499` `524`）。
2. **业务码 `ret`**：响应 JSON 里的 `ret`。行情接口常见 **HTTP 200 + `ret=5xx`**，不要只看 HTTP 状态。

`508`–`514` 与 WebSocket 错误码同号不同义。REST 只看本页，WebSocket 看 [WebSocket错误码](/getting-started/error-codes/websocket.md)。频率超限见 [HTTP接口限制](/getting-started/api-limitation/http.md)。

### 响应格式

```json
{
    "ret": 200,
    "msg": "success",
    "traceId": "698f920a-c53b-401c-bfac-4ea46b9b8f12",
    "data": []
}
```

`ret` 为 `200` 表示成功。失败时优先读 `ret` 和 `msg`，用 `traceId` 排查。

基础信息接口（`/common/basic/*`、部分 `/common/v2/basic/*`）一般只返回 `200` / `400` / `500`。

### 业务码 `ret`

| ret | 说明                                    | 服务端英文 msg                                                                  |
| --- | ------------------------------------- | -------------------------------------------------------------------------- |
| 200 | 请求成功                                  | success                                                                    |
| 400 | 参数不合法，例如 JSON 类型错误或分钟 / 小时 K 线时间戳格式错误 | Bad request / The timestamp must be a second-level timestamp（消息按原因变化）      |
| 404 | 请求的 K 线月归档包不存在                        | Archive not found: kline\_\<type>\_\<yyyyMM>                               |
| 500 | 服务端异常或未单独处理的请求错误                      | server error / Apikey not exists / 服务器内部错误，请联系管理员                          |
| 501 | 接口请求频率超过限制                            | Request frequency exceed the limit：%s times per minute                     |
| 502 | 当天请求次数已达上限；月归档下载按 API Key 的 UTC 自然日计数 | Request frequency for the day upper limit：%s                               |
| 503 | K 线数量超过限制                             | Kline quantity exceeds the limit：%s                                        |
| 504 | 盘口深度超过限制                              | Orderbook depth exceeds the limit：%s                                       |
| 505 | 产品数量超出限制                              | Products quantity exceeds the limit：%s                                     |
| 506 | 参数错误                                  | Param error：%s                                                             |
| 507 | 参数缺失                                  | Param lost：%s                                                              |
| 508 | 所有请求产品均不存在或不在可查询目录中                   | All product not exists                                                     |
| 509 | token 权限已过期                           | The token permission has expired                                           |
| 513 | 分钟 / 小时 K 线时间戳超出套餐范围，或归档月份不允许         | Timestamp limit error,earliest timestamp：%s / Month not allowed: \<yyyyMM> |
| 514 | 无市场 / 产品权限，或套餐不支持归档下载                 | No permission：%s                                                           |

REST 行情接口通常不返回 `510` / `511` / `512`。WebSocket 中的含义请参见 [WebSocket错误码](/getting-started/error-codes/websocket.md)。

### 参数与权限错误

K 线请求缺少必填参数返回 `507`；`klineNum` 小于 1 也返回 `507`。不支持的 `klineType` 返回 `506`。JSON 字段类型错误（例如将 `codes` 传成数组）返回 `400`。

批量查询会先过滤不存在的产品，全部无效才返回 `508`。对于 Free 套餐，任一有效产品不在账户允许范围内时，整次请求返回 `514`，`msg` 中会列出无权限的产品。

### 月归档下载的每日配额

[月归档下载](/rest-api/http-endpoints/post-kline-archive-download.md)耗尽当日 5 次成功请求额度后，业务响应包含重置时间：

```json
{
  "ret": 502,
  "msg": "Request frequency for the day upper limit：5",
  "traceId": "example-trace-id",
  "data": {
    "remaining": 0,
    "refreshInSeconds": 3600
  }
}
```

`refreshInSeconds` 为距离下一个 UTC 00:00 的秒数。这里的 `502` 是 JSON `ret`，不是 HTTP 502。归档缺包的 `ret=404` 同样应与下表的 HTTP 404 区分。

### 网关 / CDN（HTTP 状态，不是 `ret`）

| HTTP 状态 | 说明                                                 |
| ------- | -------------------------------------------------- |
| 401     | 认证失败。API Key 不正确，或未放在 HTTP 请求头 `apiKey` / `apikey` |
| 404     | 接口不存在                                              |
| 429     | 触发网关限流，请求不符合当前套餐配额                                 |
| 499     | 客户端主动中断，常见于网络不稳定                                   |
| 524     | 源站连接超时，一般由加速节点到源站短暂不稳定引起                           |