错误码与频控

本文档列出了原生 API 可能返回的每一个错误码。示例中的金额为示意性占位符；实时价格请调用 GET /v1/prices。

统一错误响应结构

{ "error": { "code": 4001, "slug": "insufficient_funds",
             "message": "Required 1300000 SUN, available 420000 SUN",
             "field": null, "retryable": true,
             "details": { "required_sun": 1300000, "available_sun": 420000 } },
  "request_id": "req_01J9Z5P8T3WQ7X" }

在代码中请根据 slug 或 code 进行逻辑分支，切勿仅依赖 HTTP 状态码 —— 多个不同错误可能会共享同一个状态码（例如 409 既代表幂等性冲突，也代表无法赎回的订单，而两者的业务处理方式截然相反）。后续可能会引入新的错误码： 如果遇到未识别的错误码，请按 HTTP 状态码类别处理（4xx 代表客户端请求错误，切勿盲目无限重试；5xx 代表服务端临时错误，应使用退避算法重试）。

错误码号段分布：1000–1099 鉴权与凭据 · 1100–1199 频控与配额 · 2000–2099 请求校验 · 3000–3099 业务状态 · 4000–4099 资金账户 · 5000–5099 资源供给 · 9000–9099 内部异常。

错误代码列表

参数校验错误（2000–2099）全部为 retryable: false；请根据错误信息修复请求参数，盲目重试必定返回相同错误。

供给保障机制： 下单时返回 503 是安全失败保证（fail-secure）—— 系统未做持久化且未扣款，因此使用相同的 client_order_id 重试完全安全。若发生已扣款但链上委托最终失败的情况（5002），资金已自动全额退还，订单以终态结束：请直接发起全新订单，不要重试旧单号。

重试策略规范

仅在返回 429、5xx 以及处理完原因后的 4001/4002/4004 时进行重试。切勿重试 400、401、403、404 以及非 4004 的 409 —— 这些错误需要修改请求内容或修复鉴权。创建订单时务必带上 client_order_id，以彻底避免重复购买风险。推荐使用起始延时为 250 毫秒、附带全量随机抖动（Full Jitter）的指数退避策略，单次最大延时上限设为 30 秒，总体超时建议控制在 60 秒左右 —— 超时后根据 client_order_id 查询订单实际结果。若响应中带有 Retry-After 请求头，请优先遵循该头指定的等待时长。

频控规则 (Rate limits)

频控规则基于单个 API 密钥实施，同时对单源 IP 设有底层兜底限制。每个 API 响应均携带标准响应头：RateLimit-Limit（额度）、RateLimit-Remaining（剩余次数）与 RateLimit-Reset（重置倒计时秒数）。超出限制时返回 HTTP 429、错误码 1100 rate_limited 以及 Retry-After 头。

默认限制（单个密钥，每秒请求数）：

下一步

• 身份鉴权— 1xxx 错误码的详细产生原因与签名校准。
• Webhooks 回调— order.failed 事件同样携带标准的 failure.code 和 slug。
• 订单接口参考— 了解各个接口的具体状态码定义。