Developers

错误目录

每个错误都带有稳定的、机器可读的代码和一致的 HTTP 状态。代码是您的集成应分支判断的依据：文本可能会演变，代码不会。

错误的形状

当前的形状刻意保持最小化。它是稳定的，这才是关键：一个代码，不泄露任何内部细节。

当前形状——真实响应json

{ "error": "rate_stale" }

带有可读原因——真实响应json

{
  "error": "rail_not_open",
  "reason": {
    "fr": "La retenue TDS de 1 % et l’enregistrement FIU-IND exigent une entite locale…",
    "en": "The 1% TDS withholding and FIU-IND registration require a local entity…"
  }
}

某些错误带有双语原因对象，旨在原样展示给用户。封闭通道就是其中之一：原因解释了指定的监管限制，而非故障，展示它可以节省一次支持请求。版本化 API 将在此信封中添加请求 ID，以便您能指向我们日志中的精确行。

现行代码

这些代码目前由报价端点返回。

现行代码
code	HTTP	含义	应对措施
`invalid_request`	400	请求体未通过模式验证：缺少字段、类型错误、值超出允许范围。	检查金额是字符串而不是数字，并且方向恰好是“sell”或“receive”。
`invalid_amount`	400	金额无法解析，或携带的小数位数超过资产或货币接受的范围。	截断到单位精度：USDT为6位小数，BTC为8位，欧元为2位，CFA法郎为0位。
`unknown_asset_or_rail`	404	资产或通道标识符在目录中不存在。	标识符是稳定的，永远不会重新分配。重新加载目录，而不是猜测它们。
`rail_not_open`	409	通道存在但未开放。响应携带确切原因，使用两种语言。	按原样显示原因：它解释的是监管限制，而不是故障。在同一国家提供开放的通道。
`asset_not_offered`	409	资产在目录中但未提供——适用于增强匿名资产的情况。	不要在您的选择器中提供它。目录返回它及其原因，以便您可以解释。
`rate_stale`	503	最后已知价格超过最大容忍年龄。引擎拒绝报价，而不是将过时价格作为确定价格提供。	几秒后重试。不要缓存上次成功的报价来填补空白：那正是此代码防止的错误。
`rate_unavailable`	503	此资产/货币对没有可用价格。	在您的界面中禁用该对，而不是显示估计值。显示的估计值会变成期望。
`quote_failed`	500	计算期间发生意外错误。不返回报价。	重试一次；如果错误持续存在，请使用调用的确切时间戳写信给我们。

已发布合同中的代码

这些代码伴随尚未开放的端点。它们被发布出来，以便您的错误处理一次编写完成。

现行代码
code	HTTP	含义	应对措施
`unauthorized`	401	密钥缺失、已撤销或在错误的环境中使用。	sk_test_ 密钥在生产环境中无效，反之亦然：这是有意为之。
`idempotency_conflict`	409	相同的幂等键已用于不同的请求体。	一个密钥属于一个意图。如果内容改变，密钥也会改变；否则无法判断应重放两个订单中的哪一个。
`quote_expired`	409	报价已超过其锁定窗口。	重新报价并让新金额被接受。我们绝不会在客户不知情的情况下重新定价。
`beneficiary_rejected`	422	收款人详细信息未通过支付通道验证：校验和无效、格式不符合要求，或姓名与已验证身份不匹配。	响应会指明违规字段。收款人姓名必须是已验证的身份：不允许第三方支付。
`country_not_served`	451	目的地国家不受支持：制裁、限制性措施，或缺乏当地框架。	选择451代码而非404是故意的：当我们拒绝时，我们会说明这是拒绝及其原因。
`rate_limited`	429	滑动窗口内调用次数过多。	遵守 Retry-After 头。报价排队成本低，频繁请求成本高。
`not_found`	404	资源不存在，或不属于您的密钥。	两种情况返回相同的代码：能够区分它们的响应会让任何人枚举他人的引用。

什么不是错误

超出通道边界的金额会返回有效的报价，并带有 limitError 对象。这不是失败：而是您的界面应显示的信息。

响应摘录json

"limitError": { "code": "below_min", "limit": "20.00" }

将此情况视为 HTTP 错误将使您无法获得计算出的金额，从而无法告诉用户“您比此支付方式的最低金额少 16.53 欧元”。该限制适用于净金额，即收款人收到的金额。

重试，或不重试

三个系列，三种行为。在循环中重试验证错误只会填满您的日志。

切勿重试

invalid_request、invalid_amount、unknown_asset_or_rail、asset_not_offered、unauthorized。请求有误：原样重试会得到相同结果。修复它，或显示原因。

带退避重试

rate_stale、rate_unavailable、quote_failed 以及任何速率限制。等待几秒钟，并逐渐增加尝试间隔。不要用缓存的报价填补间隔。

请求决策

rail_not_open、quote_expired、beneficiary_rejected、country_not_served。这种情况需要人工选择：提供另一通道、新报价或更正后的详细信息。