APIエラーの見方(200系・400・401・403・404・422・429・500系でどこを疑うか)

要点

400系は「送った側」、500系は「相手側」の問題が基本。401は認証(キー・トークンの誤り・期限切れ)、403は権限・プラン・IP制限、404はURLや対象ID、429は回数制限、500系は相手の障害。まずエラー本文(JSON)を読む。

ステータスコードに加えて、レスポンス本文(JSON)のエラーメッセージを必ず読む。多くの場合、原因がそのまま書いてある。確認場所はブラウザなら DevTools の Network(DevToolsのNetworkタブの見方(HTTPステータス・CSS/JS/画像・API(Fetch/XHR)・読み込み時間・キャッシュ))、サーバー側ならログ。

コード意味どこを疑うか
200 / 201 / 204成功(取得できた/作成できた/本文なし)成功なのに期待と違う → 送った条件・ページング(続きのページ)・本文の中の error 項目
400 Bad Request送った内容がおかしいJSONの書式、必須項目の抜け、型(数値を文字列で送っている)、URLの組み立て
401 Unauthorized認証できないキー・トークンが無い/違う/期限切れ、ヘッダー名や Bearer の書き方、テスト用と本番用のキーの取り違え
403 Forbidden認証はできたが権限がないキーの権限(読み取り専用など)、プランの制限、IP・ドメイン制限、WAF
404 Not Found対象が見つからないURL・バージョン(/v1/)の誤り、IDが存在しない・削除済み、別の環境(テスト/本番)を見ている
405その方法は使えないGETとPOSTの取り違え
409 / 422状態の衝突/内容の検証エラー重複登録、入力値の形式(メールアドレス・日付)
429 Too Many Requests呼び出し回数の上限短時間に呼びすぎ、ループ・再試行の暴走、キャッシュしていない。Retry-After の時間待つ
500 Internal Server Error相手側のエラー相手の障害・不具合。時間をおいて再試行、障害情報を確認。自分の送った内容が原因のこともある
502 / 503 / 504相手が落ちている・混雑・時間切れ障害情報、タイムアウトの設定、時間をおいて再試行

切り分けの順番

  1. ステータスコードとエラー本文を控える(キー・個人情報は伏せる)。
  2. 400系なら自分の送った内容(URL・方法・ヘッダー・本文)を、ドキュメントの例と1項目ずつ比べる。
  3. 500系なら相手のステータスページ・障害情報を見て、時間をおく。
  4. ブラウザでだけ失敗し、サーバーからは成功するなら CORS を疑う(CORSエラーの基本(別オリジン・ブラウザの制限・Access-Control-Allow-Origin・iframeとは別問題))。
  5. 急に動かなくなったなら、キーの期限・プラン変更・API のバージョン廃止・自分側の直前変更(障害時は直前の変更を疑う・変更履歴を残す(更新・CSS・DNS・サーバー設定・PHP・SSL・外部サービス))。

AIにエラーを見せるときは、キー・トークン・個人情報を伏せてから(渡し方は AIでトラブル原因を切り分ける方法(静的チェックで終わらせず実ブラウザで確かめる))。