HTTP 422 Unprocessable Contentとは？意味と対処方法

このエラーの意味と見分け方

• ブラウザ、APIクライアント、監視サービス、またはWebサイトチェッカーが、HTTP 422 Unprocessable Contentレスポンスを受け取ります。
• サーバーがHTTPレスポンスを返すため、リクエストはHTTP対応エンドポイントに到達しています。DNS名前解決とTLSネゴシエーションも正常に動作している可能性があります。
• 失敗はサイト全体ではなく、特定のURL、HTTPメソッド、フォーム送信、APIペイロード、またはユーザー操作に影響します。
• レスポンス本文に、無効なフィールド、値、状態、またはバリデーションルールを示すエラーメッセージが含まれる場合があります。
• レスポンスヘッダーには、キャッシュ、認証、プロキシ、レート制限、リクエスト追跡、サーバーに関する情報が含まれることがあり、発生元の特定に役立ちます。

可能性の高い順の主な原因

主な原因は次のとおりです。

1. アプリケーションのバリデーション失敗。 必須フィールドが欠落している、値が許容範囲外である、または個別には有効なフィールドの組み合わせがその操作では許可されていない可能性があります。
2. リクエストがルートの想定するメソッドまたは表現と一致していない。 URL、HTTPメソッド、Content-Type、本文の構造、またはエンコードされたデータが、エンドポイントの処理対象と一致していない可能性があります。
3. 無効なリソース状態またはビジネスルール。 リクエストの構文は正しくても、アプリケーションのルールと競合する操作など、現在の状態では実行できない場合があります。
4. サーバー側、リバースプロキシ、CDN、またはWAFのルール。 中間レイヤーがリクエストをバリデーションまたは変換し、アプリケーションに到達する前に422を返すことがあります。
5. 最近のルーティングまたはデプロイの変更。 スキーマ、シリアライザー、ミドルウェアルール、または上流連携の変更により、以前は受け付けられていたリクエストが失敗することがあります。
6. 認証または認可のコンテキスト。 アプリケーションが認証済みの操作やリクエスト状態を検証する場合、これらが関係することがあります。ただし、単純な422をログインまたは権限のエラーと自動的に診断しないでください。レスポンスとログを確認し、401や403と区別してください。

修正方法

Webサイトを閲覧している場合

1. 一度だけ再試行し、リクエストを確認する。 URL、選択したフォームの値、アップロードしたデータ、必須フィールドを確認してください。レコードの作成や制限の発動につながる可能性がある場合、同じ操作を何度も送信しないでください。
2. 通常のアカウントフローを使用する。 アカウントが必要な操作であれば、サイトの通常の画面からサインインして再試行してください。サポートへの問い合わせにパスワード、Cookie、トークンを貼り付けないでください。
3. 特定の操作だけで失敗するか確認する。 通常のページは動作するのに、1つのフォーム、アップロード、またはチェックアウト操作だけが422を返す場合は、その操作、おおよその発生時刻、画面に表示されたエラーメッセージを記録してください。
4. 適切な別のクライアントだけを試す。 サイト所有者が許可している場合、プライベートウィンドウや別の対応ブラウザを使うと、ローカルのフォームまたはセッションの問題とサーバー側のレスポンスを区別できることがあります。セキュリティ制御を回避しないでください。
5. 解消しない場合はサイト所有者に連絡する。 対象URL、判明していればリクエストの種類、発生時刻、サニタイズ済みのエラー詳細を伝えてください。認証情報、セッションCookie、決済データ、APIシークレットは送信しないでください。

開発者またはサイト所有者の場合

1. 正確なリクエストとレスポンスを記録する。 HTTPメソッド、URL、クエリパラメーター、Content-Type、本文の関連フィールド、ステータス、レスポンス本文、レスポンスヘッダーを記録してください。秘密情報と個人データはマスキングします。
2. 422が最終レスポンスであることを確認する。 リダイレクト、キャッシュされたレスポンス、またはアプリケーションのレスポンスを隠している中間レイヤーがないか確認してください。同じルートに対する既知の正常なリクエストと結果を比較します。
3. エンドポイントの契約に照らしてリクエストを検証する。 必須フィールド、データ型、許可される値、エンコード、Content-Type、リソース識別子、順序や状態に関する要件を確認してください。構文が不正な場合は別のステータスになることがあるため、意味上のバリデーションと区別します。
4. 発生元のレイヤーを特定する。 特徴的なレスポンスヘッダー、リクエストID、アクセスログ、アプリケーションログ、リバースプロキシログ、CDNの記録、WAFイベントを使い、422がアプリケーションまたは中間レイヤーのどちらから返されたかを判断します。
5. 失敗したリクエストと成功したリクエストを比較する。 メソッド、フィールド値、Content-Type、認証状態、対象リソースなど、関連する要素を一度に1つだけ変更します。実際のバリデーションルールが見えるよう、再現手順を最小限に保ってください。
6. 最近の変更を確認する。 最初に失敗した時点の前後について、デプロイ、ルート定義、スキーマ、シリアライザー、ミドルウェア、認証ポリシー、プロキシルール、キャッシュ動作、上流連携を確認します。
7. 承認済みの最小限の修正を適用する。 証拠から原因と説明できるリクエスト契約、バリデーションルール、ルート、または中間レイヤーの設定を修正します。テスト済みのロールバック計画なしに、権限、セキュリティ、キャッシュ、プロキシを広範囲に変更しないでください。
8. 安全に再テストし、周辺の動作を確認する。 可能であれば管理された環境で同じリクエストを繰り返し、その後、関連するメソッドとルートが意図したステータスを返すことを確認してください。本番環境に影響する変更の場合は、サービスの変更管理および承認手順に従います。

予防と修正確認

• 各エンドポイントで受け付けるメソッド、Content-Type、必須フィールド、許可される値、想定されるバリデーションレスポンスを文書化します。
• 適切なアプリケーション境界でリクエストデータを一貫して検証し、実行可能で機密情報を含まないエラー本文を返します。
• 必須フィールド、無効な値、リソース状態の競合、代表的なクライアントリクエストに対するテストを追加します。
• ルート、メソッド、クライアント、デプロイごとに422の発生率を監視し、回帰と通常のバリデーショントラフィックを区別できるようにします。
• ルーティング、スキーマ、プロキシ、認証、CDN、WAFの設定を、レビュー可能なバージョン管理下に置きます。
• 秘密情報と機微データをマスキングしながら、HTTPレスポンスと生成元コンポーネントを照合できる期間、リクエストIDと関連ログを保持します。
• リリース、スキーマ変更、中間レイヤーの設定更新後に、重要なフォームとAPIメソッドをテストします。

よくある質問