こんにちは！APIの開発やテスト、日々の作業で「あれ、なんで動かないんだ…？」と頭を抱えた経験はありませんか？
APIクライアントといえばPostmanが有名ですが、今回紹介する「Insomnia（インソムニア）」は、洗練されたUIと軽量さ、そしてGraphQLやgRPCへの抜群の適応力で、多くのモダンエンジニアから熱狂的な支持を集めている次世代のAPIクライアントです。
今回は、Insomniaを使い始めたばかりのあなたに向けて、その基本から「APIレスポンスのパースエラー」という誰もが一度はハマる壁を華麗に乗り越えるためのトラブルシューティングまで、現場の知見をたっぷり詰め込んで解説します。これをマスターすれば、毎日のAPIデバッグ作業が劇的に楽になりますよ！
—
1. Insomniaとは？（ツールの役割と選ばれる理由）
Insomniaは、REST、GraphQL、gRPC、SOAPなどのAPIエンドポイントに対してHTTPリクエストを送信し、そのレスポンスを確認・検証するためのオープンソース（一部機能は有料）のAPIクライアントです。
数あるAPIクライアントの中で、なぜInsomniaを使うべきなのか？
それはひとえに「開発者に認知負荷をかけない美しい設計」にあります。余計な機能そぎ落とし、リクエストの構築、環境変数の管理、レスポンスの確認という一連のフローが極めてスムーズに行えるため、コードを書くことだけに集中できるのです。
—
2. インストールと最も重要な基礎セットアップ
まずはInsomniaを手に入れましょう。
インストール手順
2. あなたのOS（Mac / Windows / Linux）に合わせたインストーラーをダウンロードし、実行します。
3. アカウント登録画面が出ますが、まずはスキップ（無料のオフラインモード）でも十分に使い始められます。
現場で絶対にやるべき「環境変数（Environment）」の基礎セットアップ
初心者のうちは、開発環境（localhost）や本番環境のURLを毎回手打ちしていませんか？ これはバグの元です。Insomniaの「Environment」機能を使って、URLやAPIキーを変数化しましょう。
画面左上のプロジェクト名をクリックし、「Manage Environments」を開きます。以下のようなJSONを設定してみてください。
{
“base_url”: “https://api.example.com/v1”,
“auth_token”: “ここに実際のBearerトークンを入れる”
}
これで、リクエストURLに `{% response ‘base_url’ %}/users` のように動的に値を埋め込めるようになり、環境の切り替えが一瞬でできるようになります。
—
3. 精度高い「Hello World」的動作確認
環境が整ったら、実際にAPIを叩いてみましょう。ここでは、誰でも無料で使えるテスト用API「JSONPlaceholder」を使用します。
1. Insomniaの画面で `+` ボタン を押し、「New Request」を選択します。
2. 以下のように設定します。
- Request Name: Get User (HelloWorld)
- HTTP Method: `GET`
- URL: `https://jsonplaceholder.typicode.com/users/1`
3. 「Send」ボタン を押します。
期待される結果:
右側のレスポンスペインに、以下のようなJSONデータと「`200 OK`」のステータスコードが表示されれば成功です！
{
“id”: 1,
“name”: “Leanne Graham”,
“username”: “Bret”,
“email”: “Sincere@april.biz”,
…
}
おめでとうございます！これでInsomniaの基本操作はマスターしました。
—
4. 【本題】APIレスポンスのパースエラーが起きた時の原因特定と解決策
さて、ここからが本題です。開発を進めていると、APIを叩いたときに以下のような絶望的な表示に遭遇することがあります。
> Error: Failed to parse JSON / Unexpected token < in JSON at position 0
「えっ、コードは合っているはずなのに、なぜ！？」
焦る必要はありません。プロのエンジニアは、エラーが出たら「どこで何が起きているのか」をレイヤーごとに切り分けて原因を特定します。
レスポンスのパースエラーが起きる主な原因と、Insomniaを使った切り分け・解決手順をみていきましょう。
—
原因1：JSONの形式不一致（HTMLやエラーメッセージが返ってきている）
先ほどの `Unexpected token <` というエラーは、「JSONを期待してパースしようとしたら、先頭に `<` があった」という意味です。つまり、サーバーがJSONではなくHTML（通常はWebサーバーやAPI Gatewayのエラーページ、例えば `502 Bad Gateway` など）を返している証拠です。
🔍 解決のためのログ確認方法：Timelineタブを見る
Insomniaの秀逸な機能の一つが、レスポンスペインにある「Timeline」タブです。ここを見ると、TCPハンドシェイクからTLS接続、送受信された生（Raw）のHTTPヘッダーやボディのすべてが時系列で確認できます。
1. レスポンスペインの 「Timeline」 をクリックします。
2. `-> Sending request…` から `<- HTTP/1.1 502 Bad Gateway` のようなやり取りを確認します。
3. サーバーが予期せぬエラー（ルーティングミスやバックエンドのクラッシュ）を起こしてHTMLを返していないか、生データを目視します。
---
原因2：認証の失敗（401 Unauthorized / 403 Forbidden）
APIの仕様が変わっていたり、有効期限切れのトークンを使っていたりすると、APIはデータを返す代わりに「認証エラー」のJSON（あるいはプレーンテキスト）を返します。これをクライアント側が無理やりパースしようとしてエラーになります。
🔍 解決手順：AuthタブとHeadersの確認
1. リクエスト設定の 「Auth」 タブを確認し、Bearer TokenやBasic認証のクレデンシャルが正しく設定されているか確認します。
2. もし環境変数（`{% response … %}` や `{% _.auth_token %}`）を使っている場合、変数の中身が空になっていないか、画面右上（または右ペイン）の環境セレクターで正しい環境が選ばれているか確認してください。
—
原因3：ネットワーク・プロキシ設定、CORSの勘違い
ローカル開発環境（Dockerや別ポートのバックエンドなど）を叩いている際によくあるのが、ネットワークのルーティングミスです。
🔍 解決手順：Timelineとプレビューの活用
1. Timelineタブで、そもそもレスポンスのステータスコードが `200` 以外になっていないか確認します。
2. レスポンスペインの表示を 「Preview」 から 「Raw」 に切り替えてみてください。「Preview」は賢くJSONやHTMLをレンダリングしようとするため、パースエラーのときに挙動がおかしくなることがあります。「Raw」で生の文字列を確認するのがバグ特定の近道です。
—
まとめ：トラブルシューティングのチェックリスト
Insomniaで「おかしな挙動」や「パースエラー」に遭遇したら、以下の順番で冷静に確認してみましょう。
1. ステータスコードを見る: `200` 以外なら、そもそもJSONが返っていない可能性が高い。
2. Timelineタブを見る: 生のHTTP通信を確認し、サーバーが何を返しているのか（HTMLか、エラーメッセージか）を暴く。
3. PreviewからRawに切り替える: データの正体を正確に把握する。
4. Environmentを見直す: URLやトークンの変数が正しく展開されているか再確認する。
API開発はエラーとの戦いですが、Insomniaという信頼できる相棒と、正しい切り分けの知識があれば、どんなバグも必ず怖くありません。
明日からのAPI開発が、よりスムーズで楽しいものになりますように！先輩エンジニアの私からは以上です。それではまた！