400・401・403・422 を見分ける API エラー切り分け手順

サーバーがリクエスト自体を正しく解釈できないなら、最初に疑うべきは 400 Bad Request です。壊れた JSON、矛盾するクエリ、誤った content-type、重複パラメータなどは、認証や権限のロジックに入る前に弾かれることがあります。

そのため 400 は 401 や 403 とは別の思考で扱う必要があります。まずはそのリクエストがサーバーにとって解釈可能な形かどうかを確認してください。

1. 実際に送られた body と headers を再構成する。
2. JSON や payload の構造を検証する。
3. query parameter や content-type を見直してから次へ進む。

この段階では、HTTP Status Code Explorer と JSON Validator を組み合わせると判断しやすくなります。

401 Unauthorized は、認証情報そのものが不足している、期限切れである、または不正であるケースを示すことが多いです。一方で 403 Forbidden は、認証は通っていても、その操作に必要な scope、role、tenant、所有権が不足しているときに返されます。

ここを混同すると、権限設計の問題なのに token を作り直したり、逆に認証ヘッダが落ちているだけなのに ACL を疑ったりします。401 なら token の存在、期限、issuer、audience、プロキシによる欠落を確認し、403 なら role や scope を確認する、という切り分けが重要です。

422 Unprocessable Entity は、構文的には読めるリクエストが、フィールド検証や業務ルールの段階で拒否されたことを示します。つまり 400 のような解析不能な壊れ方ではなく、理解はできるが受理はできない、という状態です。

そのため 422 では parser ではなく、required field、range、enum、cross-field validation などの証拠を確認すべきです。

• 400: 構造を信頼できない
• 401: 認証が成立していない
• 403: 認証は成立したが許可されない
• 422: 形式は正しいが意味的に不正

この 4 つを分けるだけで、API 障害の初動はかなり速くなります。