API連携が「両方正常なのに繋がらない」時の確認5項目と切り分けの順番

一番苦労するのは「両方正常なのに、繋がらない」

API連携のトラブルで、特に原因の切り分けに苦労するのが、**「システムAも、システムBも、それぞれは正常に動いているのに、連携だけが失敗する」**というケースです。

どちらかが壊れているなら、壊れた側を調べれば済みます。しかし、両方が正常だと、どこを調べればいいのかが、分からなくなります。この種のトラブルで、原因になりやすいのは、各システムの内部ではなく、両者の「境目」の食い違いです。主に、次の4つが、よくある食い違いです。

• データの形式が、合っていない
• 必須の項目が、足りない
• 認証の情報が、違う、または期限切れになっている
• バージョンが、合っていない

(APIそのものの意味は、APIとはで解説しています。)

なぜ、原因が見えにくいのか

連携では、一方が出したデータを、もう一方が受け取って処理します。どちらも「自分は正しく動いている」ように見えるのは、お互いに、相手がどう期待しているかを、見ていないからです。

また、エラーが出ても、「連携に失敗しました」としか表示されず、どの項目が、なぜ合わなかったのかまでは、分からないことがあります。そのため、境目を、1つずつ確認していく進め方が必要になります。

確認する5項目

特に、①から④は、「両方が正常」に見えるのに、繋がらない時の、典型的な原因です。

HTTPステータスで、原因の方向を絞る

APIは、結果を「ステータスコード」という数字で返すことが多くあります。数字の意味を知っておくと、どちらの側を疑えばよいかが見えてきます。

400番台は、こちらの送り方に原因があることが多く、500番台は、相手側に原因があることが多い、と覚えておくと、切り分けの出発点になります。ただし、サービスによって、使い方に違いがあるため、公式の説明も、あわせて確認してください。

切り分けの順番

闇雲に変更を加えるのではなく、次の順で、1つずつ確認します。

1. まず、最小のリクエストで試す:必須項目だけを入れた、一番単純なリクエストで、動くかどうかを確認する
2. 認証を、確認する:キーや権限が、使っている環境に合っているか
3. 返ってきたエラーの内容を、そのまま読む:ステータスと、メッセージを、確認する
4. 項目を、1つずつ足していく:最小のリクエストが成功したら、項目を1つ足しては、試す。失敗した時点の項目が、原因の候補になる
5. 相手側の仕様の変更を、確認する:仕様書や、更新の案内に、変更がないか

一度に複数の箇所を変えると、何が効いたのかが分からなくなります。必ず、1回に1つだけ変えてください。

トラブルの相談を受ける時に、最初に確認する3点

連携のトラブルでも、最初に確認するのは、他のトラブルと同じ3点です。

• いつから起きているか(最初から動かないのか、以前は動いていたのか)
• 何をした直後か(キーの更新、設定変更、相手側の更新など)
• 今どんな状態か(エラーの内容、ステータス)

特に、「以前は動いていた」場合は、何かが変わったことが原因です。自分たちが変えていないなら、相手側の仕様変更や、認証の有効期限切れを疑います。

AIや他の人に相談する時の注意

エラーの内容を、AIや他の人に相談する時は、次の点に気をつけてください。

• APIキー、トークン、パスワードは、必ず伏せる(貼った時点で、他者に渡ったものと考える)
• 個人情報を含むデータは、ダミーに置き換える
• 送ったリクエストの形と、返ってきたエラーを、セットで渡す

貼る前の確認には、AIに貼る前チェックが使えます。APIキーの扱いは、APIキーとはで解説しています。ログインや認証の仕組みは、OAuthとはも参考にしてください。

まとめ

• 「両方正常なのに繋がらない」の原因は、境目の食い違いであることが多い
• 確認する5項目は、認証・データ形式・必須項目・バージョン・通信と制限
• ステータスコードで、疑う方向を絞る
• 切り分けは、最小のリクエストから、1つずつ
• 相談する時は、秘密情報を伏せて、リクエストとエラーをセットで渡す

関連記事:APIのタイムアウトとリトライの決め方、冪等キー(Idempotency-Key)とは