ASP.NET Core ProblemDetails でエラーレスポンスを揃える

charter48
2026年8月16日

API のエラー形式がエンドポイントごとに違うとクライアントが辛い。ProblemDetails（RFC 7807 系）で type / title / status / detail を揃えるのが定石。

先に結論

[ApiController] の自動 400 も ProblemDetails 形式になりやすい
例外ミドルウェア／IExceptionHandler で 5xx も同じ形に寄せる
クライアントは status + type / title を見て分岐する
内部例外メッセージをそのまま detail に出さない（情報漏洩）

揃える項目

type … エラー種別の URI またはタグ
title … 短い見出し
status … HTTP ステータス
detail … 人が読む説明（本番は控えめに）
extensions … トレース ID など追加欄

実装の型

return Results.Problem(
    title: "Order not found",
    detail: "指定の注文は存在しません",
    statusCode: StatusCodes.Status404NotFound,
    type: "https://example.com/errors/order-not-found");

// コントローラなら
return Problem(
    title: "Validation failed",
    statusCode: 400);

運用上の注意

開発と本番で detail の詳細度を変える
相関 ID を extensions に入れてログと紐づける
バリデーション 400 とビジネス 409/422 を type で区別
既存クライアントが独自 JSON なら移行期間の互換を決める

関連: モデルバインディング 400 の切り分けとセットで使うと早い。

ざっくりまとめ

エラー応答の形を ProblemDetails に統一
例外経路も同じパイプに乗せる
detail と機密の線引きを先に決める

関連記事