ステータス 

べき等性キーのサポートは現時点では一部のみです。注文請求の再試行や返金請求の再試行フローなど、選択された内部再試行ミューテーションは既にべき等性キーを受け付け、下流の決済プロセッサ呼び出しの重複排除に使用しています。Zonos Graph 上のすべての顧客向け create ミューテーションに標準化された idempotencyKey 引数がまだ用意されていません — これはロードマップ上にあります。一般提供されるまで、以下のパターンを使用してミューテーションを安全に再試行できるようにしてください。

デフォルトで安全なミューテーション 

一部のミューテーションは、提供する安定した識別子による upsert であるため、本質的にべき等です。同じ入力で呼び出すと結果は同じになり、重複作成のリスクはありません。

• 一意の merchant 提供識別子（例: 注文の externalId）を受け取るミューテーションは、再呼び出し時に新規作成せず既存レコードを返します。
• 読み取り専用操作（クエリ）は常に安全に再試行できます。

作成するリソースに独自の安定した識別子を付けられる場合は、その方法を優先してください。

本質的にべき等でないミューテーションのパターン 

merchant 提供キーのないリソースを作成するミューテーションについては、クライアント側から**最大1回（at-most-once）**として扱ってください。

1. 送信前にリクエストを永続化する。 ネットワーク呼び出しの前に、自社データベースに行（ステータス pending）を書き込みます。
2. ミューテーションを送信する。 成功時は、返却されたリソース ID を pending 行に記録します（ステータス committed）。
3. ネットワークエラー時は盲目的に再試行しない。 Zonos Graph をクエリして、リソースが作成されたかどうかを確認します（例: アカウントで過去数分に作成されたリソースを一覧する、または相関付け可能な関連リソースをクエリする）。リソースが存在しないと確認できる場合にのみ再試行してください。
4. 自社データベースに一意制約を設ける。 リクエストを表すビジネスキーに対して重複再試行による二重送信を防ぎます。

Webhook 配信は at-least-once 

Zonos webhook を処理する際は、ハンドラをべき等に設計してください — 同一イベントが複数回配信される場合があります。イベント ID による重複排除を行います。イベント ID フィールドについては Webhooks を参照してください。

プラットフォームの方向性 

基盤プラットフォームは、請求再試行向けのべき等性キーフローを本番環境で既に実行しています。キーは再試行試行をスコープし、決済プロセッサ呼び出しの重複を防ぎます。顧客向け create ミューテーションにオプションの idempotencyKey 引数として同じパターンを公開する作業を進めています。指定すると、保持期間内に同じキーでの後続呼び出しすべてに対して Graph は元の応答を返します。一般提供時にこのページを更新します。

顧客向けミューテーションの標準化されたべき等性キーが統合の障害になっている場合は、サポートにお問い合わせください。