错误

契约声明的状态码、速率限制响应头，以及为什么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 对应路径单独计数。计数是声明该状态的操作数量。如需重新计算，请在仓库根目录运行：

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（冷却时间未结束，或已达累计上限）。

关于等级上限和连接数上限，请参见 速率与连接限制。

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 版本管理。