変更要約: 初版
2.2HTTP応答の解釈
API応答を構成するステータスコード（2xx成功／3xxリダイレクト／401未認証・403権限不足・404不在・429レート超過／5xxサーバ側）、応答ヘッダ（Content-Type・Retry-After・WWW-Authenticate等）、応答ボディ（エラーメッセージを含むJSON）を読み、コード＋自分が送ったリクエスト＋docsの三つ組で原因を切り分けてトラブルシュートする判断を学びます。
API連携の障害対応は「サーバが悪い/クライアントが悪い」を勘で当てる作業ではありません。HTTP応答はステータスコード・ヘッダ・ボディという三つの情報源を持ち、これらを自分が送ったリクエストとdocsの記載と突き合わせれば、原因の大半は機械的に切り分けられます。この節では、頻出コード（401/403/404/429/5xx）が「誰の・何の問題か」を示す意味を押さえ、次に取るべき一手を応答から導く力を養います。
2.2.1コードのクラスと頻出コード
- コードは百の位でクラスが分かる：2xx＝成功（
200 OK取得成功／201 Created作成成功／204 No Content成功したが本文なし）、3xx＝リダイレクト、4xx＝クライアント側の誤り（送ったリクエストに問題）、5xx＝サーバ側の障害（自分のリクエストは概ね正しくサーバが失敗）。まず4xxか5xxかで「自分を直すか・サーバ/再試行か」の初手が変わる。 - 4xxの識別が実務の要：
400＝リクエスト不正（JSON構文やパラメータ誤り）、401 Unauthorized＝未認証（資格情報が無い/無効・方式違い）、403 Forbidden＝認証済みだが権限不足（スコープ/ロール）、404 Not Found＝リソース/URL不在（エンドポイントのパス誤り含む）、429 Too Many Requests＝レート超過。401と403は「本人確認の失敗」と「権限の失敗」で対処が全く違う。 - 5xx（
500 Internal Server Error／502 Bad Gateway／503 Service Unavailable）は原則サーバ側の問題。リクエストを直しても直らないことが多く、時間を置いて再試行や運用者への連絡が現実的な一手。ただし自分の送ったデータでサーバがクラッシュしている可能性もあるため、直前に変えた値がないかは一応確認する。
2.2.2ヘッダとボディを併読する
- 応答ヘッダは次の一手のヒントを含む：
429に付くRetry-Afterは「何秒後に再試行してよいか」、401に付くWWW-Authenticateは要求される認証方式、Content-Typeは本文の形式、レート系のX-RateLimit-Remainingは残り呼び出し回数。ヘッダを読めば、当て推量せずに待機秒数や不足している認証が分かる。 - 応答ボディ（多くはJSON）には人間可読のエラー詳細が入る。例：
{"error":"invalid_token","message":"The access token expired"}。ステータスは401でも、ボディのinvalid_token/expiredまで読めば「トークン期限切れ→リフレッシュ」と一意に分かる。コードで大分類し、ボディで具体原因を確定するのが定石。
「2xx成功／4xx＝自分のリクエスト／5xx＝サーバ」「401=未認証・403=認証済みだが権限不足・404=不在・429=レート超過」「429のRetry-Afterで待機、401のWWW-Authenticateで要求方式、ボディのJSONで具体原因を確定」が頻出です。設問は「このコード＋この応答ボディ＋自分が送ったリクエスト」を突き合わせ、次の一手を選ぶ形で解きましょう。
あなたは在庫APIを叩くバッチが夜間に断続的に失敗すると報告を受けました。ログには3種の応答が混在しています。一つ目は403 Forbidden＋ボディ{"error":"insufficient_scope","message":"token lacks inventory:write"}。二つ目は429 Too Many Requests＋ヘッダRetry-After: 30。三つ目は404 Not Foundで、リクエストURLはGET /v1/itens/1234。この三つはまったく別の原因で、一律に「リトライを増やす」では解決しません。まず403は認証自体は通っており（＝401ではない）、トークンのスコープ不足が明言されています——inventory:write権限を持つトークンを発行し直す（または管理者にロール付与を依頼する）のが正解で、リトライしても永遠に403のままです。次の429はレート超過で、Retry-After: 30が「30秒待て」と明示しているので、指数バックオフ（もしくは指示秒数の待機）で再試行すればよく、ここでリトライ間隔を詰めるのは火に油です。三つ目の404は一見サーバ不在に見えますが、URLをdocsと突き合わせると正しいパスは/v1/items/1234——itensは綴り誤りで、これはクライアント側のエンドポイント誤りです。ここで学ぶべきは、同じ「失敗」でも、コードのクラス（4xx/5xx）→具体コード（403/429/404）→ボディ/ヘッダの詳細→自分のリクエスト、と突き合わせれば、それぞれに固有の一手（スコープ再発行・バックオフ・URL修正）が一意に決まることです。応答を丁寧に読まず「全部リトライ」で押すと、403と404は永久に直らず、429はかえって悪化します。
| コード | 意味 | 誰の問題か | 次の一手 |
|---|---|---|---|
| `401` | 未認証（資格情報が無い/無効/方式違い） | クライアント（認証） | 方式確認→トークン再取得/リフレッシュ |
| `403` | 認証済みだが権限不足 | クライアント（権限） | スコープ/ロールを持つ資格情報にする |
| `404` | リソース/URL不在 | クライアント（URL）またはデータ | docsとエンドポイント/IDを突き合わせ修正 |
| `429` | レート超過 | クライアント（頻度） | `Retry-After`に従いバックオフ |
| `5xx` | サーバ側の障害 | サーバ | 時間を置いて再試行/運用連絡 |
ひっかけ： 「403は認証エラーなのでトークンを再取得すれば直る」は誤りです——403は認証は成功しており（それは401）、不足しているのは権限（スコープ/ロール）なので、同じ権限のトークンを取り直しても直りません。また「404は必ずサーバ側の問題」も誤り＝エンドポイントのパスやリソースIDの綴り誤りというクライアント側原因が非常に多く、まずURLをdocsと突き合わせます。
2.2.3この節のまとめ
- コードのクラスで初手が決まる：2xx成功／4xx＝自分のリクエストを直す／5xx＝サーバ側で再試行や運用連絡
- 4xxの識別が要：401=未認証・403=認証済みだが権限不足・404=不在・429=レート超過。401と403、404のURL誤りを混同しない
- コード＋ヘッダ（
Retry-After/WWW-Authenticate）＋ボディのJSON＋自分のリクエストを突き合わせ、当て推量せず次の一手を確定する
進捗の記録にはログインが必要です。
理解度チェック
（軽い確認用）Q1. API呼び出しが `403 Forbidden` を返し、応答ボディは `{"error":"insufficient_scope","message":"token lacks devices:write"}` だった。認証トークン自体は正しく送れている。次に取るべき最も適切な対応はどれか。
Q2. バッチ処理が `429 Too Many Requests` を返し始めた。応答ヘッダに `Retry-After: 60` が付いている。処理を安定させるための最も適切な対応はどれか。
Q3. あるスクリプトが `GET https://api.example.com/v1/devces/42` で `404 Not Found` を返す。docsを確認するとデバイス取得のパスは `/v1/devices/{id}` である。他のIDでも同様に404になる。この症状の最も妥当な原因と対応はどれか。