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 | 相手が落ちている・混雑・時間切れ | 障害情報、タイムアウトの設定、時間をおいて再試行 |
切り分けの順番
- ステータスコードとエラー本文を控える(キー・個人情報は伏せる)。
- 400系なら自分の送った内容(URL・方法・ヘッダー・本文)を、ドキュメントの例と1項目ずつ比べる。
- 500系なら相手のステータスページ・障害情報を見て、時間をおく。
- ブラウザでだけ失敗し、サーバーからは成功するなら CORS を疑う(CORSエラーの基本(別オリジン・ブラウザの制限・Access-Control-Allow-Origin・iframeとは別問題))。
- 急に動かなくなったなら、キーの期限・プラン変更・API のバージョン廃止・自分側の直前変更(障害時は直前の変更を疑う・変更履歴を残す(更新・CSS・DNS・サーバー設定・PHP・SSL・外部サービス))。
AIにエラーを見せるときは、キー・トークン・個人情報を伏せてから(渡し方は AIでトラブル原因を切り分ける方法(静的チェックで終わらせず実ブラウザで確かめる))。