APIレスポンスはどこを見る？ステータスコード・ヘッダー・ボディの読み方を実務向けに整理
APIを呼んだとき、最初に確認すべきなのはステータスコード、ヘッダー、ボディの3つです。順番も重要で、実務ではまず「成功か失敗か」をステータスコードで見て、そのあとヘッダーで形式や制約を確認し、最後にボディの中身を読みます。
この流れを押さえておくと、200 OK なのに思った値が取れない、404 や 401 の原因が分からない、JSONだと思ってパースしたら失敗した、といった初歩的な詰まりを減らせます。ブラウザの開発者ツール、curl、Pythonのどれで確認するときも考え方は同じです。
- まず見るのは ステータスコード。成功か失敗か、再試行の余地があるかを判断する
- 次に ヘッダー。
Content-Type、Location、Retry-Afterなどが次の行動を決める - 最後に ボディ。JSON本文やエラーメッセージから、必要な値と失敗理由を読む
- JSONに見えても、
Content-Typeを見ずに決めつけない - 認証付きAPIでは、
Authorizationヘッダーやトークンをログにそのまま残さない
前提環境
この記事は、HTTPレスポンスの基本を理解したい初心者から実務初級者向けです。確認時点は 2026年4月25日。本文では読みやすさのため HTTP/1.1 形式で説明し、確認例には次を使います。
- CLI:
curl - Python: Python 3.9以上 の
urllib.request - テスト用エンドポイント:
httpbin.io
MDNは、HTTPメッセージの説明で「読みやすさのため HTTP/1.1 形式を使うが、HTTP/2 以降でも基本の意味は同じ」と整理しています。Pythonの urllib.request では、レスポンスオブジェクトの status 属性が 3.9 で追加 されています。
APIレスポンスはこの順で見る
最短で状況をつかむなら、見る順番は固定したほうが速いです。
ここがポイント: ステータスで成否、ヘッダーで読み方、ボディで詳細。この順に見るだけで、確認の迷いがかなり減ります。
1. ステータスコードで大枠を決める
ステータスコードは、サーバーがそのリクエストをどう扱ったかを示す3桁の数字です。MDNでは 1xx から 5xx までのクラスに分けて整理しています。
実務でまず押さえたいのは次のあたりです。
200 OK: 取得成功。GETで最もよく見る201 Created: 新規作成成功。POSTの作成系で出やすい204 No Content: 成功したが本文はない。削除や更新後によくある301302307308: リダイレクト。別URLを見に行く必要がある400 Bad Request: パラメータやJSON形式が不正401 Unauthorized: 認証情報がない、または無効403 Forbidden: 認証していても権限不足404 Not Found: URLや対象IDが違う429 Too Many Requests: レート制限500502503: サーバー側の問題
ここで重要なのは、200 以外は全部同じ失敗ではないことです。たとえば 401 は認証ヘッダーを見直す話ですが、404 はエンドポイントやパスの見直しです。429 なら再試行間隔を考える必要があります。
2. ヘッダーで「どう読めばいいか」を決める
ヘッダーはレスポンスの付加情報です。本文をどう扱うか、キャッシュしてよいか、次にどこを見るかがここで分かります。
よく使うヘッダーは次の通りです。
Content-Type: 本文の形式。application/jsonならJSONとして読むContent-Length: 本文サイズ。大きいレスポンスの把握に便利Location: 作成後やリダイレクト先のURLCache-Control: キャッシュ方針Retry-After:429や503のあと、いつ再試行するかの目安Set-Cookie: セッション情報
特に Content-Type は最優先 です。見た目がJSONっぽくても、HTMLのエラーページが返っていることがあります。その状態でJSONパースすると、原因を見誤ります。
3. ボディで必要な値と失敗理由を読む
ボディは実データです。成功時は取得結果、失敗時はエラー詳細が入ることが多くなります。
見るポイントはシンプルです。
- 成功時: 欲しいキーがどこにあるか
- 失敗時:
message、error、errorsなどの項目があるか - 配列なのかオブジェクトなのか
- ページネーション情報があるか
- 本文が空でも問題ないレスポンスか
MDNのHTTPメッセージ解説でも、本文がないレスポンスがあることに触れています。たとえば 204 No Content は成功でも本文を持ちません。本文が空だから失敗、とは限らないわけです。
curl でレスポンスを確認する基本
CLIで見るなら curl が最短です。まずはヘッダーとボディを分けて観察できるようにします。
ヘッダー込みで見る: -i
curl -i https://httpbin.io/get?foo=bar
-i はレスポンスヘッダーを本文と一緒に表示します。curl のマニュアルでは --show-headers として説明されています。
確認したい点は次の3つです。
- 先頭行の
HTTP/1.1 200 OKなど Content-TypeやContent-Length- 空行のあとに続く本文
ヘッダーだけ見る: -I
curl -I https://httpbin.io/status/418
ヘッダーだけを見たいなら -I が便利です。httpbin.io の例では、HTTP/1.1 418 I'm a teapot と各種ヘッダーが返ることが公開されています。
ボディが不要なときは、こちらのほうが読みやすくなります。
ステータスコードだけ抜き出す
curl -s -o /dev/null -w "%{response_code}\n" https://httpbin.io/status/404
期待される出力例:
404
curl は HTTP の受信自体が成功すると、404 でもコマンド失敗扱いにはしません。everything curl とFAQでも、その点が明記されています。つまり、終了コードだけ見てAPI成功と判断しないほうが安全です。
失敗時のボディも含めて見たいとき
curl --fail-with-body -i https://httpbin.io/status/429
4xx/5xx をエラー扱いにしつつ、ボディも見たい場面で使います。APIのエラー本文に原因が入る設計は多いので、ここを捨てないほうが調査が速いです。
Pythonでステータス・ヘッダー・ボディを確認する例
Pythonで確認するときも見る順番は同じです。まず status、次に headers、最後に本文を読みます。
import json
import urllib.request
url = "https://httpbin.io/get?foo=bar"
with urllib.request.urlopen(url) as response:
print("status:", response.status)
print("content-type:", response.headers.get("Content-Type"))
body = response.read().decode("utf-8")
data = json.loads(body)
print("keys:", list(data.keys()))
print("args:", data.get("args"))
出力例:
status: 200
keys: ['args', 'headers', 'origin', 'url']
args: {'foo': ['bar']}
この例で見ているのは、派手な処理ではありません。
response.statusで成否を判断するresponse.headers.get(...)で読み方を決めるresponse.read()で本文を取得するjson.loads()でJSONを辞書として扱う
業務コードでも、最初はこの形で十分です。慣れてから例外処理や再試行、タイムアウトを足せばよいです。
ありがちな見落としと直し方
初心者が引っかかりやすい点は、だいたい同じです。
200 OK だから安心してしまう
200 でも、欲しいフィールドが空だったり、別形式の本文が返っていたりします。
見るべき点:
Content-Typeは本当にapplication/jsonか- ボディの構造は想定通りか
- API仕様上、空配列や空オブジェクトが正常か
ヘッダーを見ずにJSONパースする
HTMLのエラーページやプレーンテキストをJSONとして読もうとすると失敗します。
改善例:
content_type = response.headers.get("Content-Type", "")
if "application/json" in content_type:
data = json.loads(body)
else:
print(body)
401 と 403 を同じ扱いにする
この2つは似ていますが、直す場所が違います。
401: トークン切れ、未設定、形式ミスを疑う403: 権限やスコープ不足を疑う
同じ「認証まわりの失敗」に見えても、修正の打ち手は別です。
トークンをそのまま表示する
API確認ではヘッダーを見たくなりますが、Authorization: Bearer ... をそのまま画面共有やログ保存に残すのは危険です。
最低限の対策として、次を徹底したいところです。
- トークンは環境変数で渡す
- 共有用ログではトークン値をマスクする
- 開発者ツールのスクリーンショットに認証情報を残さない
実務でよくある確認パターン
ここまでの基本を、作業場面ごとに短く整理します。
API仕様を読みながら動作確認するとき
- ステータスコードが仕様どおりか
- 成功時と失敗時でボディ構造が変わるか
LocationやRetry-Afterのような重要ヘッダーがあるか
障害切り分けをするとき
404: URL、パス、ID、末尾スラッシュ401: トークン、署名、期限切れ429: レート制限と再試行間隔500系: サーバー側問題か、一時的な障害か
画面から呼んでいるAPIをブラウザで追うとき
- Networkタブでレスポンスヘッダーと本文を見る
Content-Typeとステータスコードを先に確認する- フロント側エラー表示より、API本文のメッセージを優先して読む
代替手段と使い分け
APIレスポンスを見る方法は1つではありません。用途で分けると迷いにくくなります。
curl: すばやく再現したいときに向く- ブラウザ開発者ツール: フロントから実際に飛んだ通信を追うときに向く
- Python: 確認をスクリプト化したいときに向く
最初の一歩としては、curl -i で全体像を見て、必要なら Python で自動確認に移す流れが実務では扱いやすいです。
最後に確認したいポイント
APIレスポンスの読み方で迷ったら、次だけ覚えておけば十分です。
- ステータスコードで成否を決める
- ヘッダーで本文の扱い方を決める
- ボディで必要な値とエラー理由を読む
200でも中身は必ず確認する- 認証ヘッダーは表示しすぎない
レスポンス確認で次に差が出るのは、429 の再試行設計と、成功時・失敗時でボディ構造が変わるAPIへの対応です。基本の3点を見慣れたら、次はその2つを自分のAPI確認手順に入れると実務で崩れにくくなります。