REST API エラーのデバッグ方法:CORS、401、403、404、415、タイムアウト

著者:Sayaib Sarkar更新日:9 分で読めます

このページの内容 9 セクション

要点:失敗したリクエストをアプリの外で再現し、何よりも先にステータスコードとレスポンスボディを読み、一度にひとつだけ変えましょう。API のバグの多くはいくつかのパターンに分類でき、どれに当たるかはステータスコードが教えてくれます。ブラウザーに「blocked by CORS policy」と表示されるのに、同じリクエストが API クライアントでは動く場合、問題はリクエストではなくサーバーの CORS ヘッダーです。

このガイドでは、API を組み込むときによく出会うエラー、それぞれが本当に意味すること、そして VS Code から数分で原因を確かめる方法を説明します。

ステップ 1:アプリの外でリクエストを再現する

アプリには、HTTP ライブラリ、インターセプター、プロキシ、ブラウザーといった層が重なっています。まずそれらを取り除きましょう。

  1. ブラウザーで DevTools → Network を開き、失敗したリクエストを右クリックして Copy → Copy as cURL を選びます。
  2. VS Code で DevSnip Pro の REST API クライアントを開き、cURL コマンドをアドレスバーに貼り付けます。メソッド、ヘッダー、ボディがインポートされます。
  3. 送信します。これで、ヘッダーをひとつずつ変えて、その効果をすぐに確認できます。

リクエストがここでは動くのにブラウザーでは失敗するなら、CORS のセクションに進みましょう。どちらでも失敗するなら、下のステータスコードがどこを見るべきかを教えてくれます。

ステータスコードとボディを読む

コードを変える前に、サーバーが返したものを読みましょう。多くの API はレスポンスボディで問題を説明しています。たとえば {"error": "invalid_token", "error_description": "The access token expired"} です。

ステータスよくある意味最初に確認すること
400 Bad Requestボディやパラメーターが無効レスポンスボディ、必須フィールド、JSON の構文
401 Unauthorized有効な認証情報が送られていないAuthorization ヘッダー、トークンの有効期限
403 Forbidden認証情報は有効だが、この操作は許可されていないトークンのスコープやロール、API キーの権限
404 Not FoundURL が違う、またはリソースが存在しないベース URL、パス、末尾のスラッシュ、API のバージョン
405 Method Not AllowedURL は正しいが、メソッドが違うGET か POST か、Allow レスポンスヘッダー
415 Unsupported Media Typeサーバーがボディの形式を読めないContent-Type ヘッダー
422 Unprocessable EntityJSON としては有効だが、検証に失敗したレスポンスボディのフィールドごとのエラー一覧
429 Too Many Requestsレート制限に達したRetry-After ヘッダー
5xxサーバーが失敗したサーバーのログ、別の入力なら動くか

401 Unauthorized:認証情報が届いていないか、有効でない

  • ヘッダーはそもそもあるか?HTTP クライアントによっては、別のホストへのリダイレクトをたどるときに Authorization を落とします。リクエストを組み立てるコードではなく、実際に送られたリクエストを確認しましょう。
  • 形式は正しいか?ほとんどの API は、スペースがちょうど 1 つで Bearer が 1 回だけの Authorization: Bearer <token> を期待しています。トークンをプレフィックス付きで保存していると、Bearer Bearer … と重複するバグがよく起こります。
  • トークンの有効期限は切れていないか?JWT を DevSnip Pro の JWT Decoder & Signer に貼り付けると、ヘッダーとクレームを表示し、exp をチェックします。aud(オーディエンス)と iss(発行者)も API が期待する値と比べましょう。デコーダーはローカルで動作するので、本物のトークンが Web サイトに送られることはありません。

403 Forbidden:誰であるかは問題ないが、していることが許されていない

サーバーはあなたが誰かを知っていますが、トークンやキーにこの操作の権限がありません。トークンのクレームにあるスコープやロール、API キーの権限、リソースが別のアカウントやテナントに属していないかを確認しましょう。新しいトークンの権限が多くない限り、新しいトークンで同じリクエストを再試行しても解決しません。

ファイアウォールや WAF がリクエストをブロックしたとき(たとえば User-Agent がない場合)に 403 を返すサーバーもあります。その場合、レスポンスボディは JSON ではなく HTML のエラーページのように見えることがよくあります。

404 Not Found と 405 Method Not Allowed

URL を API のドキュメントと 1 文字ずつ比べましょう:

  • ベース URL と API のバージョン(/v1/ か /v2/ か)。
  • 末尾のスラッシュ:多くのサーバーでは /users と /users/ は別のルートです。
  • /users/undefined や /users/{id} のように、置き換えられていないパスパラメーター。

ホストをリクエストごとに直接書くのではなく、{{baseUrl}} のような環境変数を使えば、この種のミスをまとめてなくせます。パスが正しいのに 405 が返る場合は、ルートは存在するもののそのメソッドには対応していません。Allow レスポンスヘッダーに受け付けるメソッドが示されます。

415 と 400:ボディがサーバーの期待と違う

JSON のボディには Content-Type: application/json が必要です。これがないと、多くのフレームワークはボディをまったく解析せず、ハンドラーには空に見えます。その結果、415 になったり、送ったはずの必須フィールドがないと訴える 400 になったりします。

HTTP
POST /v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer <token>

{"name": "Ada", "role": "admin"}

サーバーがフォームデータを求めている場合は、application/x-www-form-urlencoded を送ります(OAuth のトークンエンドポイントは多くがそうです)。送信前に JSON のボディを API のスキーマと照らし合わせるには、DevSnip Pro の JSON Schema Validator を使います。すべての違反をパス付きで一覧表示します。

CORS:「blocked by CORS policy」

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.apiTimeout が既定値(30 秒)を設定し、リクエストごとのタイムアウトがそれより優先され、Cancel でリクエストを途中で止められます。

そしてコードで直す

リクエストが API クライアントで動いたら、同じ呼び出しを JavaScript(fetch または Axios)、Python、Go、Java、C# で生成して、自分のコードと比べましょう。違いはたいてい、ヘッダー、ボディのエンコード、URL のどれかです。

自分のエディターで試してみよう

無料・アカウント不要・ローカルで動作。Windows、macOS、Linux の VS Code 1.93 以降と JetBrains IDE に対応。

code --install-extension sayaib.hue-console