> For the complete documentation index, see [llms.txt](https://docs.nexus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexus.xyz/api-reference/zh-cn/guides/errors.md).

# 错误

契约声明的状态码、速率限制响应头，以及为什么401不会告诉您任何信息。

每个生成的端点页面都会列出该操作声明的状态。本页说明每个状态码在整个 API 中的含义，以及契约有意少说的两处地方。

## 错误模型

| 状态    | 含义         | 说明                                                                                                                                                                                                                                                                                                                      |
| ----- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | 成功         | 123个操作                                                                                                                                                                                                                                                                                                                  |
| `201` | 已创建        | 5个操作。`POST /orders` 和 `POST /orders/batch` 及其 `/api/v1` 对应路径，以及 `POST /api/v1/bridge/withdrawals`。                                                                                                                                                                                                                      |
| `101` | 切换协议       | 两个 WebSocket 升级路径                                                                                                                                                                                                                                                                                                       |
| `400` | 校验错误       | 50个操作。在契约定义了机器可读 `code` 的地方，响应体会携带该值，例如 `invalid_window`、`bad_wallet`、`bad_agent`、`expiry_out_of_range`、`invalid_json`。订单拒绝涵盖保证金不足、最小价格变动无效、订单不可修改以及违反保证金要求。                                                                                                                                                            |
| `401` | 身份验证失败     | 89个操作。**所有401响应都有意返回同样不透明的响应体 `{"code":"unauthorized"}`，以防止信息泄露**。401不会告诉您*原因*。密钥错误、签名错误、时间戳过期和会话过期看起来完全一样。请先检查时钟偏差。                                                                                                                                                                                                    |
| `403` | 禁止访问       | 25个操作。对订单、资金、杠杆、保证金和跨链桥提现等写操作的司法辖区管控拒绝，对调用方的来源是永久性的，因此请勿重试。管理端点（需要管理员 secret）。运营方冻结额度发放时的 `POST /account/credit`（`credits_frozen`）。`GET /account/deposit-target` 上的 `EARLY_ACCESS_REQUIRED`。`POST /withdrawals` 上被拒绝的提现。`/transfers` 操作上的 `TRANSFER_ACCOUNT_INELIGIBLE` 或 `TRANSFER_OUTFLOW_BLOCKED`。                   |
| `404` | 未找到，或不归您所有 | 26个操作。所有权校验失败返回404而非403，因此您无法借此探查其他账户的资源。                                                                                                                                                                                                                                                                               |
| `409` | 冲突         | 7个操作。代理注册时的 `duplicate_agent`。下单时，`client_id` 已被一个不再挂单的订单占用。修改订单时的市场生命周期准入限制。在 `POST /api/v1/bridge/withdrawals` 上以不同金额重复使用 `Idempotency-Key`。`POST /transfers` 上的 `TRANSFER_ID_CONFLICT`。                                                                                                                              |
| `422` | 无法处理       | 1个操作。`POST /account/margin-mode` 收到语义无效的数据、未知字段，或 `cross`、`isolated` 以外的 `margin_mode`。格式错误的 JSON 返回 `400`。                                                                                                                                                                                                             |
| `426` | 需要升级       | 1个操作。`POST /account/deposit` 中，已验证的服务密钥在 `X-Account-Id` 请求头中发送了入账账户。请改为在已签名的请求体中发送 `account_id`。                                                                                                                                                                                                                        |
| `429` | 超出速率限制     | 74个操作。见下文。                                                                                                                                                                                                                                                                                                              |
| `500` | 内部错误       | 3个操作。`POST /auth/login` 上会话存储写入失败时的 `INTERNAL_ERROR`，以及 `GET` 和 `POST /account/margin-mode` 上的意外内部错误。                                                                                                                                                                                                                   |
| `502` | 上游不可用      | 14个操作。在 `/account/summary` 和 `/account/state` 及其 `/api/v1` 对应路径上为 `authoritative_margin_unavailable`：以引擎为准的保证金视图暂时不可用。依据该视图推导余额的端点会**故障关闭**，返回错误，而不是一个本地估算、可能不安全的数值。这是暂时性的，请稍候重试。其余为邀请数据读取接口上的 `BAD_GATEWAY`、资金快照上的 `FUNDING_SOURCE_*`、`POST /api/v1/bridge/withdrawals` 上失败的下游步骤，以及 `/transfers` 操作上的 `TRANSFER_*` 结果。 |
| `503` | 服务不可用      | 11个操作。`GET /account/deposit-target` 上的 `DEPOSIT_TARGET_MISCONFIGURED`、邀请数据读取接口上的 `REFERRAL_STORE_NOT_CONFIGURED`、`/transfers` 操作上的 `TRANSFERS_UNAVAILABLE`、`POST /api/v1/bridge/withdrawals` 上提现不可用，以及 `POST /account/margin` 上无法持久记录的保证金调整。                                                                            |

一个操作指 `openapi.json` 中的一个路径加一个方法，每个 `/api/v1` 对应路径单独计数。计数是声明该状态的操作数量。如需重新计算，请在仓库根目录运行：

```bash
python3 -c 'import json, collections; d = json.load(open("eng/apps/exchange/api/openapi.json")); print(sorted(collections.Counter(code for item in d["paths"].values() for method, op in item.items() if method in ("get", "put", "post", "delete", "patch") for code in op.get("responses", {})).items()))'
```

### 429与速率限制响应头

`429` 的响应体形如 `{"code":"RateLimitExceeded","tier":"Pro"}`，响应携带：

| 响应头                     | 含义              |
| ----------------------- | --------------- |
| `X-RateLimit-Limit`     | 您的等级每秒允许的请求数    |
| `X-RateLimit-Remaining` | 当前窗口内剩余的请求数     |
| `X-RateLimit-Reset`     | 限制重置时的 Unix 时间戳 |
| `Retry-After`           | 重试前需等待的秒数       |

请依据 `X-RateLimit-*` 响应头控制节奏，而不是盲目重试。有两个端点将 `429` 用于与速率限制无关的含义：`POST /account/credit`（每日额度已用完，于 UTC 午夜重置）和 `POST /faucet`（冷却时间未结束，或已达累计上限）。

关于等级上限和连接数上限，请参见 [速率与连接限制](https://docs.nexus.xyz/exchange/apis-and-rates/rate-limits)。

## CCXT 兼容性

### API 版本支持

版本标识符是本契约已发布的规范标签。边缘服务在 `/metadata` 公布其接受的版本，该路径由边缘服务提供，**不是**本契约中的操作。它返回 `current_api_version`（所提供的最新标签）和 `min_api_version`（仍被接受的最旧标签），使客户端和代理可以通过程序读取支持窗口。

1.0之前（`v0.x.y`），破坏性变更很频繁，`min_api_version` 可能随任何破坏性版本前移。一个已发布的标签在被后续版本取代后至少仍支持**14天**，1.0之后该窗口会加宽。如果请求的 `X-Nexus-Api-Version` 指定了一个可识别但早于 `min_api_version` 的标签，会收到机器可读的 `426 Upgrade Required`（`api_version_unsupported`），并附带当前规范的链接，以便工具发现版本偏差并升级。由于该请求头未经身份验证，这一限制只是兼容性辅助手段，而不是安全控制。伪造该值只会放宽限制。

另请参见 [API 版本管理](https://docs.nexus.xyz/exchange/apis-and-rates/api-versioning)。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nexus.xyz/api-reference/zh-cn/guides/errors.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.