公開日 2026/10/26

API連携でデータが重複・欠落するのはなぜ？再送・照合・復旧の設計

カテゴリー：

システム開発

タグ：

システム開発

API連携でデータが重複・欠落するとき、原因は「通信エラー」だけではありません。送信後に応答が途切れた、同じ通知が再送された、片側だけ更新された、認証が切れた、入力形式が合わなかったなど、失敗の位置によって対処は変わります。業務システム同士をつなぐ場合は、正常時の同期手順と同じくらい、失敗時の照合・再送・人手復旧を決めておくことが重要です。

この記事はAPIの実装コードではなく、受発注、顧客、在庫などのデータ連携を検討する企業担当者向けに、何を確認すれば重複や欠落を減らせるかを整理します。どの連携先でも同じ方法で防げるとは限らず、相手側のAPI仕様と現行業務の条件を確認する必要があります。

最初に「どのデータが正しいか」を決める

二つのシステムに同じ顧客や注文があるとき、どちらを正本とするかが曖昧だと、再送時に古いデータで上書きしたり、両方で別の番号を発行したりします。連携対象の項目ごとに、作成・更新・削除を行うシステムと更新の優先順位を決めます。

顧客・注文など、何のデータを連携するか
送信元と受信先、正本となるシステム
両システムで共通に追跡できるID
新規登録、更新、取消をどう区別するか
同じデータが何度届いたらどう扱うか

画面上の名称が同じでも、必須項目や値の意味が異なる場合があります。項目対応表と変換ルールを残しておくと、失敗した一件を元の業務データまで追跡しやすくなります。

連携IDを付け、応答不明時は相手側を照会してから再送する流れ — 図1：応答がないことは処理されなかった証拠ではない。

API連携で重複が起きる典型例

送信側が注文作成APIを呼び、受信側では登録が成功したものの、返答だけがネットワークで失われたとします。送信側からは成功か失敗か分かりません。そのまま同じ内容をもう一度「新規登録」すると、注文が二件になる可能性があります。HTTPの応答を受け取れなかったことと、相手側で処理されなかったことは同じではありません。

再送を安全にするには、取引ごとに一意の連携IDを付ける、同じIDの再実行を一回の処理として扱う、登録前に相手側の状態を照会するといった方法を検討します。どれが使えるかは相手のAPI仕様によります。例えばStripeの冪等リクエストの説明は、同じ操作の再試行で重複作成を防ぐためのキーを示しています。これはStripe固有の仕様例であり、他のAPIにも同じ仕組みがあると決めつけないでください。

例：注文登録の応答だけが途切れたら

架空の受注連携で、送信側の注文ID「ORD-001」を相手側へ登録します。相手側では受注が作成されましたが、応答が途中で切れ、送信側には結果が届きません。送信側はまず「処理結果不明」と記録し、同じ注文IDまたは連携IDで相手側の登録状態を照会します。登録済みなら再登録せず、相手側IDを保存して成功にします。

相手側が冪等キーを受け付け、同一キーの再送が安全だと仕様で確認できた場合は、その条件に従って再試行します。照会方法も冪等性もない場合は「応答がなかったから再送」と決めつけず、人が相手側の管理画面や記録で確認してから復旧します。Stripeの方式は公式ドキュメントにある一例で、他社APIにも同じ条件があるとは限りません。

欠落が起きる位置を分けて確認する

送信元で対象データが抽出されなかった、抽出後の変換に失敗した、送信待ちで止まった、受信側で入力不正として拒否された、受信後の登録に失敗した――欠落の原因は工程ごとに違います。件数だけを見ると、どの段階で止まったかが分かりません。送信元ID、連携ID、実行時刻、処理段階、相手の応答、再処理の状態を追えるようにします。

一定件数の差異は日次の件数照合で見つけられますが、値のずれや取消漏れは件数が一致していても見落とします。重要な取引では、金額、状態、更新日時など、業務上意味のある項目まで照合する必要があります。照合の頻度はリアルタイム、日次、月次のどれが必要かを業務影響で決めます。

件数が同じでも、IDと状態まで照合する

例えば送信元が100件、受信先も100件でも、送信元の1件が欠けて別の1件が重複していれば件数は一致します。連携ID単位で「送信済み」「登録済み」「失敗」「保留」を突き合わせ、差異を一覧化してください。金額や取消状態のような業務上重要な項目も対象にします。

差異の種類	見つけ方	担当者が確認すること
欠落	送信元IDが受信先にない	抽出条件、変換失敗、送信待ち、入力拒否
重複	一つの連携IDに複数の受信先ID	再送履歴と相手側の登録時刻
値・状態のずれ	IDは一致するが金額や取消が異なる	変換ルール、更新順序、部分成功

一時障害、入力・認証不正、部分成功を分けた再送判断 — 図2：再送可能かどうかは相手APIの仕様と状態で判断する。

自動再送してよいエラー、止めるべきエラー

一時的なネットワーク不通、相手サービスの一時障害、回数制限などは、条件を決めて再試行できる場合があります。ただし短時間に無制限に繰り返すと、相手への負荷や重複処理の危険が増えます。AWSの再試行と待機時間の設計資料は、待機時間を延ばす方式と、再試行時には処理の冪等性を確認する必要性を示しています。

一方、必須項目不足、無効な認証情報、権限不足、廃止されたAPI仕様などは、同じ内容を再送しても直りません。入力内容や設定を人が修正してから再処理する流れへ切り替えます。再試行回数の上限、通知先、失敗データの保管期間も決めておきます。

手動復旧できる状態を作る

失敗データを単にログへ出すだけでは、担当者がどの注文や顧客に影響したかを判断しにくくなります。エラー一覧に業務ID、発生時刻、失敗理由、処理済みかどうか、再送可否を表示し、修正・再送後に相手側の状態まで確認できるようにします。キューを使う構成では、処理できないメッセージを別に保管して調査する設計もあります。Microsoftのデッドレターキューの説明はその一例です。

「再送」ボタンを押す前に、前回の処理が一部成功していないか確認できることが重要です。訂正のために元データを変更した場合は、誰が何を直したかも記録します。復旧手順が担当者の記憶だけに依存していると、夜間障害や人員交代時に対応が遅れます。