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…"
  }
}

一部のエラーには、ユーザーにそのまま表示することを意図したバイリンガルの理由オブジェクトが含まれます。閉鎖された送金手段はその1つです。理由は、名前付きの規制上の制約を説明し、障害ではないため、表示することでサポートリクエストを節約できます。バージョン管理された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	同じ冪等キーが、異なるリクエスト本文で既に使用されています。	キーは1つのインテントに属します。内容が変わればキーも変わります。そうでなければ、2つの注文のどちらを再生すべきか区別がつきません。
`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ユーロ不足しています」とユーザーに伝えることができなくなります。制限は、受取人が受け取る正味金額に適用されます。

再試行するかどうか

3つのファミリー、3つの動作。検証エラーをループで再試行しても、ログが埋まるだけです。

再試行しない

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。状況には人間の選択が必要です。別の送金手段、新しい見積もり、修正された詳細を提供してください。