外部サービスとの連携が止まり、自分側のログと相手の管理画面を見比べて「どちら側で失敗しているのか」を落ち着いて切り分けている一人運用の保守担当者
保守・改修約13分

外部API連携の不具合｜相手側か自分側かを切り分ける順番

「決済が通らないと連絡が来て確認したら、こちらのコードは何も変えていない」——。 外部サービスとの連携（決済、配送、地図、SMS、認証など、社外のAPIとやり取りする仕組み）を保守していると、この「自分は触っていないのに急に動かない」に何度もぶつかりますよね。相手先のAPIは自分では中を見られません。だから「うちのバグなのか、相手側の障害なのか」が分からないまま、ログとにらめっこする時間が生まれます。あの、原因が自分の管理下にあるかも分からない宙ぶらりん、地味に消耗します。

でも、外部API連携のトラブルは、いきなり全部を疑わなくて大丈夫です。最初にやることはただ一つ、「失敗しているのは自分側か、相手側か」を分けること。ここさえ分ければ、次に動くべき相手（自分のコードか、相手先のサポートか）が決まり、無駄な犯人捜しがぐっと減ります。

この記事では、外部APIとの連携が急に動かなくなったとき、やみくもにコードやネットワークを触る前に、どこを見て「どっち側の問題か」を切り分けるかの順番を一緒に整理します。全部を一度に調べるのではなく、判断に効く手がかりから順に見ていく話です。

結論：まず「相手からの返事（レスポンス）を実際に見る」ことから始めます（推測で切り分けない）。そのうえで、①つながっているか（そもそも相手に届いているか）→②ステータスコードとエラー本文（4xxなら自分側・5xxなら相手側が疑わしい）→③認証・期限（トークン切れ・鍵・IP制限）→④相手の障害情報（ステータスページ・仕様変更の告知）の順に見ていきます。「返事の中身」を1回つかまえた時点で、どちら側を追うべきかはほぼ決まります。焦って自分のコードを書き換える前に、「まず相手の返事を1回記録する」ことをゴールにします。

連携の作りは現場ごとに違います（同期で待つのか、キューで非同期に投げるのか、リトライがあるのか）。順番と考え方を出発点に、自分の現場の仕組みに置き換えて使ってください。

何が起きているか：見えないのは「相手が自分の管理下にない」から

外部API連携がやっかいなのは、症状が複雑だからではなく、トラブルの半分が自分の見えないところ（相手側）で起きているからです。自分のサーバーやログは見られても、相手のサーバーの中は見られません。だから「動かない」の原因が、次のどこにあるのかが最初は分かりません。

つまり必要なのは「気合いでコードを読み返す」ことではなく、相手の返事を証拠として押さえ、自分側・相手側・あいだのどこで止まっているかを分ける目です。次から、その順番を見ていきます。

「どっち側か」を分ける4つのステップ

疎通・ステータスコード・認証・相手の障害情報の順に見て自分側か相手側かを切り分ける流れ図
「疎通→返事→認証→相手」の順に見る。手前から一つずつ、どちら側かを分けていく

大事なのは、判断に効く手がかりから先に見ることです。多くの「連携が動かない」は、①疎通か②相手の返事の中身で、どっち側かがはっきりします。いきなりコードの中身を読み込むと、そもそも相手に届いていないだけ、という時間の無駄が起きます。

① まず「つながっているか」を確かめる（そもそも届いているか）

最初にやるのは、コードを疑うことではなく、リクエストが相手に届いているかを確かめることです。ここで「届いてすらいない」と分かれば、コードより先に経路（ネットワーク）を見ることになります。

ここで届いていない・拒否されるなら、犯人はあいだの経路か相手のダウンです。コードは触らず経路と相手の状況へ。届いていて返事が返るなら、次の②でその返事の中身を読みます。

ここで一呼吸。「自分のせいか分からない」時間は、腕を疑う時間ではなく、証拠をそろえる時間です。相手が見えないのは、あなたの落ち度ではありません。

② ステータスコードとエラー本文を読む（4xxか5xxか）

つながって返事が返るなら、次はその返事の中身です。HTTPのステータスコード（相手が結果を数字で返す約束事）とエラー本文は、どっち側かを分ける一番の手がかりです。

ここで4xxで、本文に「この項目が足りない/不正」と書いてあるなら、犯人は自分側（の送り方）です。5xxやメンテナンス表示なら、相手側の問題として動きます。コードは、どちらか決まってから読み始めれば十分です。

③ 認証・期限を疑う（トークン切れ・鍵・IP制限）

「昨日まで動いていたのに、コードは変えていない」の犯人で多いのが、この層です。時間の経過で失効するものは、こちらが何もしなくても、ある日から急に止まります。

この層は、「いつから」動かないかが強い手がかりになります。特定の日時からきれいに止まっているなら、その時刻に期限が切れた・鍵が変わった・IPが変わった可能性を疑います。

④ 相手の障害情報・仕様変更を確かめる（自分の外の事情）

手前を全部そろえて「どうやら相手側だ」となったら、相手の状況を一次情報で確かめます。ここまで来れば、動くべき相手（相手先のサポート）がはっきりしています。

この層に来たら、自分側を無理にいじらないのが安全です。相手側の問題を自分のコードで力技回避すると、相手が直したときに今度はその回避策が事故になります。まずは「相手が直るまでの一時対処（リトライ・キュー・ユーザーへの案内）」と「恒久対応（相手復旧後に戻す）」を分けて考えます。

具体例：「決済APIが夕方から急にエラーになる」

よくある報告で、順番に切り分けてみます。

犯人は「決済APIの障害」ではなく、②の返事（401）を入り口に、③の認証（トークン更新バッチの停止）でした。もし最初から決済処理のコードを読み込んでいたら、コードは正しいので迷子になっていたはずです。手前から「返事の中身」を押さえて「どっち側か」を分けたからこそ、見るべき場所（更新バッチ）が一気に絞れました。

影響：切り分けの順番を持つと、何が変わるか

「どっち側か」を分ける順番を1枚持っておくと、直す力そのものより先に、焦りと板挟みが減ります。

逆に、順番を持たずに毎回「とりあえずコードを読み返す」だけだと、実は相手側の障害だった日に半日を溶かす、ということが起きます。順番は、宙ぶらりんな時間を短くする道具です。

明日やること：連携の「切り分けメモ」を1枚作る

立派な設計書は要りません。明日できる、いちばん小さな一歩はこれです。

  1. いま連携している外部APIについて、「返事を1回、そのまま記録する」方法を確かめる（ステータスコードとエラー本文がログに残るか）。残っていなければ、まずそこを残す設定にする。
  2. 上の①疎通→②返事→③認証→④相手の順に、「トラブル時にどこを見るか」を1行ずつ書き出す。
  3. 「いつから動かないか」を確認する場所（相手のステータスページのURL、トークン更新ジョブのログの場所）を、メモに控えておく。
  4. 次に不具合が来たら、コードを開く前に②の返事をまず1回つかまえて、4xxか5xxかで「どっち側か」を分ける。
  5. 分けた結果と対応（自分側で直した／相手に連絡した）を1行残す。次の連携トラブルで、同じ手探りをしないで済みます。

きれいにまとめなくて大丈夫です。「返事をどこで見て、どっち側かをどう分けるか」の1枚があるだけで、次の自分（や相談する相手）が、いちばんつらい宙ぶらりんの時間を短くできます。

「外部API連携トラブル」切り分けチェックリスト

調査に着手するとき、これだけ確認できているかを見る項目です。コピーして、自分のメモに当ててみてください。全部を毎回そろえる必要はありません。

まず外せない最低ラインはこの3つです。焦っていても、ここだけは押さえます。

次の項目は、手前で切り分かないとき・相手側が疑わしいときに追加で確認します。当てはまらなければ飛ばして大丈夫です。

全部に○が付かなくても大丈夫です。最低ラインの3つ、とくに「相手の返事を1回そのまま見る」さえ押さえられれば、自分のせいかと抱え込んで消耗するより、ずっと確かな一歩になります。

よければ、こちらも

外部API連携のトラブルは、「返事を1回つかまえて、どっち側かを分ける」ところまで来れば、あとは原因調査の技が効いてきます。返事を残すログの見どころと、原因特定・記録の残し方をセットにしておくと、次の「急に動かない」がだいぶ軽くなります。

相手側の障害か自分側かを切り分けられ、次に動くべき相手が定まって肩の力が抜けた保守運用の担当者

外部API連携のトラブルがこわいのは、原因が自分の見えないところにあるかもしれないまま、自分のせいかと抱え込んでしまうからです。でも、まず相手の返事を1回つかまえて、①疎通→②返事→③認証→④相手の順に「どっち側か」を分けると決めるだけで、霧はかなり晴れます。多くの場合、あなたのコードは正しくて、ただ相手側の事情や期限切れが隠れていただけです。 今日は、連携している外部APIの「返事がログに残っているか」を確かめるところからで十分です。その1枚が、次の「急に動かない」を、宙ぶらりんな時間ではなく手順に変えてくれます。

ほかの実務ヒントは記事一覧からどうぞ。保守運用の小さな備えを、メールでも少しずつお届けしています。

関連用語