# 报错与重试

34 个错误码用同一个结构：每个都写明扣没扣费、要不要重试、该改什么。报错一律扣 $0.00，只有 settlement_unknown 这 1 个例外，它自己会写明。

## 一个报错长什么样

所有接口都是这个结构，连没进到任何接口的请求也是。

```json
{
  "code": "insufficient_balance",
  "request_id": "8199dc1a-af29-4911-80c8-437718bfa8fb",
  "message": "The balance is too low",
  "message_zh": "余额不足",
  "charged": false,
  "retry": "after_fix",
  "required": "0.002",
  "available": "0.0009",
  "docs_url": "https://dataxapi.com/docs/errors#insufficient_balance"
}
```

## 字段

前六个每次都有，其余的有内容时才出现。

### 每次都有

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 固定的错误代码。程序里按它判断，不要按文字判断。 |
| `request_id` | string | 这次请求的编号，响应头 `X-Request-Id` 里也有。找我们时带上它。 |
| `message` | string | 一句英文说明，取自下面这张表。 |
| `message_zh` | string | 同一句话的中文。 |
| `charged` | boolean \| null | `false` 是没扣费。`null` 是不知道，只有 `settlement_unknown` 会这样，不能当成没扣。 |
| `retry` | string | `no` 不要重试，`yes` 可以，`once` 只能再试一次，`after_fix` 改了再试，`same_key` 只能用同一个幂等键再发。 |

### 有内容时才出现

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `retry_after_seconds` | integer | 要等多少秒，和响应头 `Retry-After` 是同一个数。 |
| `param` | string | 出问题的那个参数。 |
| `problems` | array | 参数错在哪，逐条列出。 |
| `reason` | string | 同一个代码下的哪一种：不存在还是私密，速率还是并发，Key 的日、月还是总额上限。 |
| `required` | string | 这次调用需要多少钱，美元。 |
| `available` | string | 余额或这把 Key 的上限还剩多少。 |
| `docs_url` | url | 这个代码在本页的链接。 |

## 全部错误代码

一共 34 个。只有一个可能已经扣费，它自己会写明。

| HTTP | 代码 | 含义 | 代码、含义、怎么办 | 扣费 | 重试 |
| --- | --- | --- | --- | --- | --- |
| 400 | `invalid_params` | 参数不合法 | 改掉 `param` 指出的参数，`problems` 里逐条写了错在哪。 | 不扣 | 改了再试 |
| 400 | `request_not_served` | 这种参数组合现在取不了 | 去掉或换掉其中一个参数。接口页上写了哪些组合能用。 | 不扣 | 改了再试 |
| 400 | `max_price_exceeded` | 这次调用的最高价超过了你设的上限 | 把 `X-Max-Price` 调高或者不带。`required` 是这次最多要多少。 | 不扣 | 改了再试 |
| 400 | `cursor_invalid` | 游标不存在 | `next_cursor` 要原样传回，或者从第一页重新开始。 | 不扣 | 不能 |
| 400 | `cursor_mismatch` | 游标不是用这个接口和这组参数取得的 | 游标只能配它当初那个接口和那组参数用。 | 不扣 | 改了再试 |
| 401 | `unauthorized` | 没有带凭证，或凭证无效、已停用、已过期 | 在 `Authorization: Bearer` 里带上你的 Key，并到控制台确认这把 Key 还在用。 | 不扣 | 不能 |
| 402 | `insufficient_balance` | 余额不足 | 充值。`required` 和 `available` 是需要多少、还剩多少。 | 不扣 | 改了再试 |
| 402 | `key_budget_exceeded` | 超出这把 Key 的金额上限 | 到控制台调高这把 Key 的上限，或者换一把 Key。`reason` 写明超的是日、月还是总额。 | 不扣 | 改了再试 |
| 402 | `run_budget_exceeded` | 超出这一轮任务的金额或次数上限 | 开一轮新的任务，预算设大一些。一轮任务的预算不能追加。 | 不扣 | 不能 |
| 403 | `account_suspended` | 账户已停用 | 请联系我们。恢复之前调用都不会成功。 | 不扣 | 不能 |
| 403 | `forbidden` | 这个凭证不能带这个选项 | 去掉这个凭证不能带的那个请求头。 | 不扣 | 不能 |
| 403 | `key_scope_denied` | 这把 Key 不能调用这个接口 | 到控制台把这个接口加进这把 Key 的范围，或者换一把有权限的 Key。 | 不扣 | 不能 |
| 404 | `not_found` | 对象不存在、私密或已删除 | 不用重试。`reason` 写明是不存在，还是私密或已删。 | 不扣 | 不能 |
| 404 | `result_not_found` | 没有这个请求号的结果 | 核对请求号。已经释放的调用没有结果可读。 | 不扣 | 不能 |
| 404 | `run_not_found` | 没有这个运行编号 | 核对运行编号。 | 不扣 | 不能 |
| 404 | `unknown_endpoint` | 没有这个接口 | 对照 API 参考核对路径。路径就是接口编号把点换成斜杠。旧路径会在 `moved_to` 里写明搬去了哪。 | 不扣 | 不能 |
| 409 | `call_in_progress` | 这个幂等键的调用还在执行，稍后用同一个键再取 | 稍等一下，用同一个 `Idempotency-Key` 把同样的请求再发一次。 | 不扣 | 只能用同一个幂等键 |
| 409 | `idempotency_conflict` | 这个幂等键已用于另一个请求 | 新的请求用一个新的键。 | 不扣 | 改了再试 |
| 410 | `cursor_expired` | 游标已过期，请从第一页重新开始 | 从第一页重新开始。`page.cursor_expires_at` 会提前告诉你什么时候过期。 | 不扣 | 不能 |
| 410 | `result_expired` | 结果只保留 24 小时，已删除 | 重新调一次。这是一次新的调用，照常收费。 | 不扣 | 不能 |
| 410 | `run_expired` | 这一轮任务已到期，不能再发起调用 | 开一轮新的任务。 | 不扣 | 不能 |
| 429 | `rate_limited` | 请求过快或同时进行的调用过多 | 有 `retry_after_seconds` 就等这么久；没有的话，等你自己进行中的调用结束一个。 | 不扣 | 能 |
| 429 | `cost_cap_exceeded` | 这个账户今天的额度已用完 | 等到 `Retry-After` 给出的时间。 | 不扣 | 能 |
| 429 | `uncharged_cost_limit` | 这个账户今天没取到数据、也没扣费的调用太多，这类接口到明天（UTC）再调 | 等到明天（UTC），`Retry-After` 给出了时间。被限的只是没取到数据、也没扣费的那类调用。 | 不扣 | 能 |
| 500 | `settlement_unknown` | 这次调用的结算状态未知，请用同一个幂等键或请求号查询 | 不要当成没扣费。用同一个 `Idempotency-Key` 把同样的请求再发一次，或者按请求号查这次调用。 | 不确定 | 只能用同一个幂等键 |
| 500 | `internal_error` | 服务内部出错 | 重试。这次占用的金额已经放回。 | 不扣 | 能 |
| 502 | `upstream_failed` | 数据来源出错 | 重试。带同一个 `Idempotency-Key`，不会扣第二次。 | 不扣 | 能 |
| 502 | `upstream_changed` | 数据来源返回的结构变了 | 稍后重试。修好之前接口可能会自动暂停，状态页会写明。 | 不扣 | 能 |
| 502 | `upstream_unclear` | 数据来源的返回无法判断，最多重试一次 | 重试一次，还不行就停。 | 不扣 | 只能再试一次 |
| 502 | `cursor_unavailable` | 这个游标所在的数据来源现在不可用，稍后重试或从第一页重新开始 | 稍后重试，或者从第一页重新开始。 | 不扣 | 能 |
| 503 | `upstream_busy` | 数据来源繁忙，请稍后重试 | 等 `retry_after_seconds` 秒再试。 | 不扣 | 能 |
| 503 | `capability_paused` | 这个接口已暂停 | 看状态页，接口恢复后再试。 | 不扣 | 能 |
| 503 | `overloaded` | 服务繁忙，请稍后重试 | 等几秒再试。 | 不扣 | 能 |
| 504 | `timeout` | 没有在时限内取到数据，可以用同一个幂等键重试 | 用同一个 `Idempotency-Key` 重试。 | 不扣 | 能 |

---

目录修订号 c48ce454ae6c4c65。 [网页版](https://dataxapi.com/zh/docs/errors/)