API の JSON レスポンスの読み方とデバッグ方法
連携がうまくいかないとき、答えはたいていレスポンスのボディにあります。このガイドでは、レスポンスを取得し、読みやすくして、問題の原因を示すフィールドを見つける方法を紹介します。
1. レスポンス全体を取得する
Web ページが送るリクエストには開発者ツールのネットワークタブを、それ以外には curl を使います。curl -i ならボディに加えてステータスコードとヘッダーも表示され、JSON を読む前にエラーの原因が分かることもよくあります。
レスポンスは全体をコピーしてください。ログやターミナルで途中で切れたレスポンスは、閉じかっこが足りないため整形できません。
2. まずステータスコードを確認する
| ステータス | 意味 | ボディで確認するもの |
|---|---|---|
| 200、201 | 成功 | 要求した、または作成したデータ |
| 400、422 | リクエストが不正 | フィールドと検証メッセージの一覧 |
| 401、403 | 権限がない、または不足 | トークンやスコープに関するヒント |
| 404 | 見つからない | パスや ID が間違っていないか |
| 429 | リクエストが多すぎる | 再試行までの時間やレート制限の詳細 |
| 500〜504 | サーバーまたはゲートウェイのエラー | API 提供元に伝えるリクエスト ID |
3. 読みやすくする
レスポンスを JSON 整形ツールに貼り付けます。ヘッダーや JSONP のコールバックで始まる場合は取り除かれます。\" がたくさん見える場合は二重エンコードされているので、ツールがデコードします。
ツリー表示に切り替えて大きな配列を折りたたみましょう。多くの API は結果を data、items、results などのフィールドに入れ、ページ送りの情報を meta、links、next などに入れています。
4. ページ送りをたどる
一覧は通常いくつかのページに分かれています。next、next_cursor、page、total などのフィールドを探してください。カーソルは呼び出しごとに変わることがあるため、次のページは自分で URL を組み立てず、API が返すカーソルや URL を使って取得します。
5. 数値と日付に注意する
15〜16 桁を超える ID は JavaScript で丸められることがあります。API が文字列の ID を用意していればそちらを使いましょう。日付は通常 2026-01-15T09:30:00Z のような ISO 8601 形式の文字列で、Z は UTC を意味します。現地時間への変換は表示するときだけにしましょう。