本文へ移動
KAIHATSU

外部APIが止まっても業務を戻せるか。連携機能の検収項目

外部API障害の検収では、入力保持、処理記録、再開方法を失敗の種類別に合意し、納品と追加対応の境界を明確にします。通信不可や処理結果不明を分け、見積依頼から納品確認までの判断基準を整理します。

執筆・確認株式会社adding 編集部

order-guide / contract

外部API障害の検収では、「失敗したときにエラーが出る」だけを合格条件にしてはいけません。発注者と開発会社が合意すべきなのは、業務データを反映してよいか、入力が残るか、誰が何を確認して再開するか、処理記録から経緯を追えるかです。

外部サービスへつながらない場合と、送信はされたものの結果だけ受け取れない場合では、同じ再試行でも危険性が違います。前者では業務を再開できても、後者でそのまま再送すれば重複処理につながりかねません。納品時には失敗を五つに分け、それぞれの表示、保持、記録、再開方法を確認します。

ただし、どこまでを当初見積もりに含めるかは、連携先の仕様と対象業務によって変わります。障害受入票を見積依頼の段階から共有し、標準の納品条件、発注者側の運用、追加開発を行ごとに切り分ける必要があります。

外部API障害の検収を一つのエラー確認で済ませない

HTTPの仕様上も、失敗の意味と次の行動は同じではありません。2026年9月21日時点のIETF「RFC 9110: HTTP Semantics」では、401は有効な認証資格情報がない状態、403は要求を理解したうえで実行を拒否した状態です。同じ資格情報で401になった場合は新しい資格情報へ差し替えて再要求できますが、403に同じ資格情報で自動再送することは推奨されていません。

上流との連携失敗にも差があります。同仕様では、502は上流から不正な応答を受けた状態、503は一時的な過負荷や保守で処理できない状態、504は上流から適時に応答を得られない状態です。過負荷時でも必ず503になるとは限らず、接続自体が拒否される場合があります。したがって、特定のステータスコードだけを待つ検収では、通信不可を取りこぼします。

制限はさらに別です。2026年9月21日時点のIETF「RFC 6585: Additional HTTP Status Codes」では、429は一定時間内の要求過多を表し、次の要求までの待ち時間をRetry-Afterで示せます。一方、資源保護のため接続が落とされ、常に429が返るとは限りません。復旧操作は「失敗したらすぐ再試行」と一律に決めず、観測できた状態に応じて切り替えます。

五つの状態を分ける障害受入票

以下は運用上の提案です。見積依頼時に空欄を埋め、納品時には「発生条件」と「期待結果」を再現して確認します。連携先が試験用の失敗応答を用意していない場合は、代替の確認方法と、それで合格とする責任者も合意してください。

障害の分類検収で与える条件利用者への表示・入力保持再開操作残す処理記録追加範囲を判断する条件
通信不可外部側から応答を受け取れない状態未完了であることと、利用者が次に取る操作を示す。再入力が必要か、入力を保持するかを決める安全に再実行できる操作を用意するか、運用担当へ引き継ぐ対象の業務操作、失敗した連携、未完了の状態自動復旧、監視通知、滞留分の一括再開まで求めるなら、当初見積もりに含まれるかを確認する
認証失敗無効な資格情報または権限拒否を受ける状態単なる通信失敗とせず、利用者が操作を続けても解消しないことを示す資格情報の更新か権限確認へ分岐し、同じ資格情報での無条件な再送を避ける認証または権限で拒否されたこと、対象連携、確認状況資格情報の更新画面、期限前通知、権限申請まで開発対象にするかを分ける
制限429、Retry-After、または接続切断として観測される要求過多連打を促さず、待機または再開方法を示す。入力の扱いも固定するRetry-Afterがあれば待機判断に使い、なければ合意した運用へ渡す制限として判定した根拠、待機判断、再開結果待機の自動制御、要求の保留、管理者による再開をどこまで含めるかを決める
応答不正想定した形式や内容として扱えない応答を受ける状態成功と表示せず、業務データへの反映を止めたことを示す調査後に再取得または再処理する。通信不可と同じ自動再試行にはしない受信した応答を調査できる記録、反映を止めた状態、対応結果連携先の仕様変更への追随、変換規則の追加、過去分の補正を変更対応とする条件を決める
処理結果不明外部側へ要求した後、完了応答を受け取る前に接続が閉じる状態成功とも失敗とも断定せず、確認中として扱う。入力から同じ要求を重ねない外部側の処理有無を照会または照合し、重複を避けてから再開する元の要求と照合できる情報、確認結果、再開の判断結果照会、照合用の台帳、重複防止の仕組みが連携先で実現できるかを調査範囲として切り出す

この表の合否は、利用者が業務をどの状態から戻せるかで判定します。未完了の入力が消える、管理者が対象処理を見つけられない、再開後に元の処理との関係を追えないといった結果であれば、画面に警告が出ても合格にはできません。

「処理結果不明」は再送の前に照合する

登録、送信、決済依頼のように、同じ要求を繰り返すと同じ結果になるとは限らない操作では、応答を受け取れなかったことと、外部側で処理されなかったことは同義ではありません。2026年9月21日時点のRFC 9110は、非冪等な要求について、処理が実質的に冪等だと分かる手段、または元の要求が適用されなかったと検出できる手段がなければ、自動再試行すべきではないとしています。応答前に接続が閉じたという理由だけでPOSTを再送することも、危険な方法として説明されています。

そこで運用上の提案として、処理結果不明の行には次の三点を必須で書きます。

  • 外部側の処理有無を、どの情報で照会または照合するか
  • 確認が終わるまで、利用者の再操作と自動再送をどう止めるか
  • 未処理と確認できた後、元の入力と記録を使ってどう再開するか

三点を決められない場合、開発会社だけに「重複なく復旧すること」を約束させても検収できません。連携先に照会手段があるかを調査し、ない場合は照合用の台帳や人による確認を運用へ置くのか、別の連携方法を選ぶのかを発注者が判断します。

応答不正は業務反映を止めて確認する

通信に成功しても、受け取ったデータを予定どおり処理できるとは限りません。2026年9月21日時点のRFC 9110では、Content-Typeは応答表現のメディアタイプを示し、データ形式と受信側での処理方法を定めます。また、502は上流から不正な応答を受けた状態です。接続できたことだけを合格にせず、想定した応答として扱えない場合に成功表示や業務反映を行わないことを確認します。

運用上の提案として、検収用の条件には、想定外の形式を受けた場合、必要な内容を読み取れない場合、上流の不正な応答として通知された場合を含めます。ただし、どの内容を必須とするかは連携先の公開仕様と合意した設計で決める事項です。受信内容をどこまで記録するかも、調査の必要性だけでなく、取り扱う情報の性質を踏まえて案件ごとに決めます。

見積依頼で納品条件と追加対応を分ける

障害受入票は、完成後のテストに加え、見積依頼の条件整理にも使います。システム開発の要件定義チェックリスト|外注前に決める10項目も参照し、対象業務、外部連携、受け入れ条件、運用責任者を見積依頼前に結び付けます。

運用上の提案として、各行を次の区分で合意すると、納品と追加対応の境界を判断しやすくなります。

  • 納品条件:失敗を誤って成功扱いせず、入力、表示、記録、再開が合意どおりに動く
  • 発注者の運用:資格情報の更新、権限確認、連携先への問い合わせ、結果の照合を担当する
  • 追加候補:自動復旧、滞留処理の一括再開、管理画面、監視通知、仕様変更への追随を別途判断する
  • 未確定:連携先の試験環境や結果照会の可否を調査してから、範囲と受け入れ方法を確定する

区分名だけでは足りません。誰が実行するか、何を見て完了とするか、成果物のどこへ残すかまで受入票に書きます。見積書の工程と対象外を比較するときは、システム開発の見積もりの取り方と内訳|妥当性の判断基準も確認してください。

納品時に合格とする状態

納品時は、五つの行について、合意した条件を与えた結果と処理記録を発注者が確認します。連携先の都合で再現できない行は、試験用の代替応答、設計上の確認、運用手順の実施など、何を代替証拠とするかを先に決めます。再現できないこと自体を合格扱いにせず、未確認として引き渡す条件も明記します。

とりわけ、処理結果不明は「通信エラー」と同じ再送操作に流さず、確認中の状態で止めます。外部側の結果を照合でき、未処理と確認してから再開できるなら、業務を戻す道筋があります。照合手段がなく、発注時にも未確定だった場合は、調査結果と当初合意の差分を確認し、変更範囲かどうかを判断します。障害受入票の各行に合格条件、運用担当、追加条件が残っていれば、発注者は「どの状態から、誰が、何を確認して戻すか」に沿って連携機能を受け入れられます。

費用、期間、契約、法務・税務上の扱いは条件により異なります。記事の確認日とリンク先の一次情報を確認し、個別判断は専門家へご相談ください。

システム開発・発注ガイドへ戻る