REST API エラーのデバッグ方法:CORS、401、403、404、415、タイムアウト
このページの内容 9 セクション
要点:失敗したリクエストをアプリの外で再現し、何よりも先にステータスコードとレスポンスボディを読み、一度にひとつだけ変えましょう。API のバグの多くはいくつかのパターンに分類でき、どれに当たるかはステータスコードが教えてくれます。ブラウザーに「blocked by CORS policy」と表示されるのに、同じリクエストが API クライアントでは動く場合、問題はリクエストではなくサーバーの CORS ヘッダーです。
このガイドでは、API を組み込むときによく出会うエラー、それぞれが本当に意味すること、そして VS Code から数分で原因を確かめる方法を説明します。
アプリには、HTTP ライブラリ、インターセプター、プロキシ、ブラウザーといった層が重なっています。まずそれらを取り除きましょう。
- ブラウザーで DevTools → Network を開き、失敗したリクエストを右クリックして Copy → Copy as cURL を選びます。
- VS Code で DevSnip Pro の REST API クライアントを開き、cURL コマンドをアドレスバーに貼り付けます。メソッド、ヘッダー、ボディがインポートされます。
- 送信します。これで、ヘッダーをひとつずつ変えて、その効果をすぐに確認できます。
リクエストがここでは動くのにブラウザーでは失敗するなら、CORS のセクションに進みましょう。どちらでも失敗するなら、下のステータスコードがどこを見るべきかを教えてくれます。
コードを変える前に、サーバーが返したものを読みましょう。多くの API はレスポンスボディで問題を説明しています。たとえば {"error": "invalid_token", "error_description": "The access token expired"} です。
| ステータス | よくある意味 | 最初に確認すること |
|---|---|---|
400 Bad Request | ボディやパラメーターが無効 | レスポンスボディ、必須フィールド、JSON の構文 |
401 Unauthorized | 有効な認証情報が送られていない | Authorization ヘッダー、トークンの有効期限 |
403 Forbidden | 認証情報は有効だが、この操作は許可されていない | トークンのスコープやロール、API キーの権限 |
404 Not Found | URL が違う、またはリソースが存在しない | ベース URL、パス、末尾のスラッシュ、API のバージョン |
405 Method Not Allowed | URL は正しいが、メソッドが違う | GET か POST か、Allow レスポンスヘッダー |
415 Unsupported Media Type | サーバーがボディの形式を読めない | Content-Type ヘッダー |
422 Unprocessable Entity | JSON としては有効だが、検証に失敗した | レスポンスボディのフィールドごとのエラー一覧 |
429 Too Many Requests | レート制限に達した | Retry-After ヘッダー |
5xx | サーバーが失敗した | サーバーのログ、別の入力なら動くか |
- ヘッダーはそもそもあるか?HTTP クライアントによっては、別のホストへのリダイレクトをたどるときに
Authorizationを落とします。リクエストを組み立てるコードではなく、実際に送られたリクエストを確認しましょう。 - 形式は正しいか?ほとんどの API は、スペースがちょうど 1 つで
Bearerが 1 回だけのAuthorization: Bearer <token>を期待しています。トークンをプレフィックス付きで保存していると、Bearer Bearer …と重複するバグがよく起こります。 - トークンの有効期限は切れていないか?JWT を DevSnip Pro の JWT Decoder & Signer に貼り付けると、ヘッダーとクレームを表示し、
expをチェックします。aud(オーディエンス)とiss(発行者)も API が期待する値と比べましょう。デコーダーはローカルで動作するので、本物のトークンが Web サイトに送られることはありません。
サーバーはあなたが誰かを知っていますが、トークンやキーにこの操作の権限がありません。トークンのクレームにあるスコープやロール、API キーの権限、リソースが別のアカウントやテナントに属していないかを確認しましょう。新しいトークンの権限が多くない限り、新しいトークンで同じリクエストを再試行しても解決しません。
ファイアウォールや WAF がリクエストをブロックしたとき(たとえば User-Agent がない場合)に 403 を返すサーバーもあります。その場合、レスポンスボディは JSON ではなく HTML のエラーページのように見えることがよくあります。
URL を API のドキュメントと 1 文字ずつ比べましょう:
- ベース URL と API のバージョン(
/かv1/ /か)。v2/ - 末尾のスラッシュ:多くのサーバーでは
/とusers /は別のルートです。users/ /やusers/ undefined /のように、置き換えられていないパスパラメーター。users/ {id}
ホストをリクエストごとに直接書くのではなく、{{baseUrl}} のような環境変数を使えば、この種のミスをまとめてなくせます。パスが正しいのに 405 が返る場合は、ルートは存在するもののそのメソッドには対応していません。Allow レスポンスヘッダーに受け付けるメソッドが示されます。
JSON のボディには Content-Type: application/ が必要です。これがないと、多くのフレームワークはボディをまったく解析せず、ハンドラーには空に見えます。その結果、415 になったり、送ったはずの必須フィールドがないと訴える 400 になったりします。
POST /v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer <token>
{"name": "Ada", "role": "admin"}サーバーがフォームデータを求めている場合は、application/ を送ります(OAuth のトークンエンドポイントは多くがそうです)。送信前に JSON のボディを API のスキーマと照らし合わせるには、DevSnip Pro の JSON Schema Validator を使います。すべての違反をパス付きで一覧表示します。
CORS を強制するのはブラウザーだけです。curl、Postman、モバイルアプリ、サーバー間の呼び出しは CORS を無視します。だから同じリクエストが API クライアントでは動き、Web アプリでは失敗することがあるのです。修正はいつもサーバー側です。ページのオリジンに対して、正しい Access-Control-* ヘッダーを送る必要があります。
よくある原因:
Access-Control-Allow-Originヘッダーがない、または別のオリジンになっている。http:/と/ localhost:3000 http:/は別のオリジンです。/ localhost:5173 - プリフライトの
OPTIONSリクエストが失敗する。JSON のボディやAuthorizationヘッダーを持つリクエストはプリフライトを発生させます。サーバーがそれに401、404、405を返すと(認証のミドルウェアが CORS より先に動いていることが多い)、ブラウザーは本来のリクエストをブロックします。 - 認証情報付きでワイルドカードを使っている。Cookie を使う場合(
credentials: 'include')、サーバーは正確なオリジンとAccess-Control-Allow-Credentials: trueを返す必要があります。Access-Control-Allow-Origin: *は使えません。 - エラー時に CORS ヘッダーがない。サーバーが CORS ヘッダーなしで
500を返すと、ブラウザーは CORS エラーとして報告し、本当のエラーを隠してしまいます。エラーレスポンスにも CORS ヘッダーを付けましょう。
DevSnip Pro の CORS Builder & Debugger には、そのための 3 つのモードがあります。コンソールのエラーを貼り付けて考えられる原因と修正方法を得る、レスポンスヘッダーを貼り付けてブラウザーと同じようにチェックする、そして Express、NestJS、Next.js、Fastify、nginx、FastAPI 向けの正しい設定を生成する、の 3 つです。
- そもそも何かが待ち受けているかを確認しましょう。DevSnip Pro の Port & Network Toolkit は、どのローカルポートが空いているかを表示します。API が使うはずのポートが空いているなら、サーバーはそこで動いていません。
- スマートフォンやエミュレーターから
localhostへのリクエストは、パソコンではなくデバイス自身に向かいます。マシンの LAN アドレスか、エミュレーターのホスト用エイリアスを使いましょう。 - 大きなレスポンスや遅いエンドポイントには、長めのタイムアウトが必要な場合があります。DevSnip Pro では、
devsnip.が既定値(30 秒)を設定し、リクエストごとのタイムアウトがそれより優先され、Cancel でリクエストを途中で止められます。apiTimeout
リクエストが API クライアントで動いたら、同じ呼び出しを JavaScript(fetch または Axios)、Python、Go、Java、C# で生成して、自分のコードと比べましょう。違いはたいてい、ヘッダー、ボディのエンコード、URL のどれかです。