> 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/en-docs/getting-started/error-codes/rest-api-error-codes.md).

# REST API Error Codes

How HTTP APIs report errors.

Treat these as two separate number spaces:

1. **HTTP status** from the gateway / CDN (`401` `404` `429` `499` `524`).
2. **Business `ret`** in the JSON body. Quote endpoints often return **HTTP 200 + `ret=5xx`**. Do not read only the HTTP status.

`508`–`514` collide with WebSocket codes and mean different things. Use this page for REST only. See [WebSocket Error Codes](/en-docs/getting-started/error-codes/websocket-error-codes.md) for sockets. Rate limits: [REST API Limitation](/en-docs/getting-started/api-limitation/rest-api-limitation.md).

### Response envelope

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

`ret=200` is success. On failure read `ret` and `msg` first; keep `traceId` for support.

Basic-info endpoints (`/common/basic/*` and some `/common/v2/basic/*`) usually return only `200` / `400` / `500`.

### Business `ret`

| ret | Meaning                                                                                                   | Server English `msg`                                                          |
| --- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| 200 | Success                                                                                                   | success                                                                       |
| 400 | Invalid parameters, such as malformed JSON fields or an invalid seconds timestamp for minute/hour candles | Bad request / The timestamp must be a second-level timestamp (message varies) |
| 404 | Requested monthly candle archive package does not exist                                                   | Archive not found: kline\_\<type>\_\<yyyyMM>                                  |
| 500 | Server exception or request error without a dedicated handler                                             | server error / Apikey not exists / 服务器内部错误，请联系管理员                             |
| 501 | Per-minute request limit exceeded                                                                         | Request frequency exceed the limit：%s times per minute                        |
| 502 | Daily request allowance exhausted; monthly archives count by API key and UTC calendar day                 | Request frequency for the day upper limit：%s                                  |
| 503 | Candlestick count exceeds the limit                                                                       | Kline quantity exceeds the limit：%s                                           |
| 504 | Order-book depth exceeds the limit                                                                        | Orderbook depth exceeds the limit：%s                                          |
| 505 | Symbol count exceeds the limit                                                                            | Products quantity exceeds the limit：%s                                        |
| 506 | Parameter error                                                                                           | Param error：%s                                                                |
| 507 | Required parameter missing                                                                                | Param lost：%s                                                                 |
| 508 | All requested symbols are unknown or absent from the queryable product list                               | All product not exists                                                        |
| 509 | Token permission expired                                                                                  | The token permission has expired                                              |
| 513 | Minute/hour candle timestamp outside the plan window, or an archive month is not allowed                  | Timestamp limit error,earliest timestamp：%s / Month not allowed: \<yyyyMM>    |
| 514 | Market/symbol access denied, or the plan does not allow archive downloads                                 | No permission：%s                                                              |

REST quote APIs do not normally return `510` / `511` / `512`. For their WebSocket meanings, see [WebSocket Error Codes](/en-docs/getting-started/error-codes/websocket-error-codes.md).

### Parameter and permission errors

Missing required candle parameters return `507`; `klineNum` below 1 also returns `507`. An unsupported `klineType` returns `506`. Invalid JSON field types, such as an array for `codes`, return `400`.

Batch queries filter unknown symbols and return `508` only when none are valid. On the Free plan, if any valid symbol is outside the account permissions, the whole request returns `514` and `msg` lists the denied symbols.

### Daily quota for monthly archives

After the 5 successful requests per day allowed for [monthly archive downloads](/en-docs/rest-api/market-data/post-kline-archive-download.md) are exhausted, the business response includes the reset countdown:

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

`refreshInSeconds` is the number of seconds until the next 00:00 UTC. This `502` is the JSON `ret`, not HTTP 502. An archive response with `ret=404` is likewise different from the HTTP 404 below.

### Gateway / CDN (HTTP status, not `ret`)

| HTTP status | Meaning                                                                             |
| ----------- | ----------------------------------------------------------------------------------- |
| 401         | Auth failed. API key is invalid or missing from the HTTP `apiKey` / `apikey` header |
| 404         | Endpoint not found                                                                  |
| 429         | Gateway rate limit                                                                  |
| 499         | Client closed the request                                                           |
| 524         | Origin timeout between the CDN and the origin                                       |