For AI agents: the complete documentation index is available at /Practical-Introduction-to-Spring-Boot/llms.txt, the full documentation bundle is available at /Practical-Introduction-to-Spring-Boot/llms-full.txt, and this page is available as Markdown at /Practical-Introduction-to-Spring-Boot/SpringBoot入門/RFC9457エラー応答入門.md.

Spring Boot + RFC 9457 によるエラー返却入門

講義の区切り

タスク API の事前準備を済ませた状態で、基本編の目安は 90 分です。終了条件は「同じ 409 でクライアントの判断がどう変わるか、どの入力違反をまとめられるかを説明できる」です。 発展内容は、MockMvc、problem type の登録と契約管理、メディアタイプ交渉です。 準備と前後の章は 学習ガイド で確認できます。

概要

HTTP API のエラーを、RFC 9457 が定義する Problem Details の形式で返します。 同じ形式を使いながら、標準メンバーだけで返す方法、独自の問題種別を定義する方法、複数の問題をまとめる方法を扱います。 「どの情報を標準に任せ、どこからアプリの契約にするか」を判断できることを目指します。

対象読者

  • Spring Boot で REST API を作成できる方
  • エラー応答の形式を API の契約として設計したい方
  • RFC 9457 の用語と Spring の ProblemDetail の対応を知りたい方

事前準備と到達目標

Java 21、Maven Wrapper、Spring Boot 4.0 系を使います。 例外処理・エラー応答入門 の基本部分を前提にします。 Advice による共通化と HTTP ステータスの対応を先に確認しておくと、この資料の差分が分かりやすくなります。

Spring Initializr で Maven / Java / Jar / YAML を選び、新しいプロジェクトを作成します。 パッケージ名は dev.mikoto2000.springboot.rfc9457 にします。 依存関係は Spring Web と Validation です。講義までに「DTO と業務例外の作成」「Service と Controller の作成」を済ませ、アプリを起動できる状態にします。講義では「パターン1」から進みます。

完了時には、次の 3 つを自分の言葉で説明できることを目指します。

  1. 標準メンバーだけで返すとき、何を利用者に伝えられるか。
  2. 独自の type を定義するとき、何を契約として固定するか。
  3. 複数の問題を 1 つの応答にまとめるとき、何に注意するか。

この資料の構成

この資料は 2 部構成です。

  1. 触って学ぶ RFC 9457 エラー返却: 3 つの返し方を実装し、curl で比べるハンズオン。契約テストは発展。
  2. 座学で学ぶ RFC 9457 エラー返却: 仕様の用語、type の設計、複数問題の扱いを整理する座学。
触って学ぶ(ハンズオン)座学で学ぶ(理論)
パターン1: 標準メンバーだけで返すRFC 9457 の位置づけと標準メンバー
パターン2: 独自の type を定義するtype の設計と problem type の登録
パターン3: 複数の問題をまとめる複数問題の扱いと拡張メンバー
応答と Content-Type の確認application/problem+json と content negotiation
MockMvc による契約の検証(発展)契約としてのエラー応答とセキュリティ

触って学ぶ RFC 9457 エラー返却

題材とするタスク API

小さなタスク管理 API を使います。3 つの失敗場面が、そのまま 3 つの返し方に対応します。

場面失敗返し方
存在しないタスクを取得する404パターン1: 標準メンバーだけで返す
完了済みタスクをもう一度完了する409パターン2: 独自の type を定義して返す
入力が不正400パターン3: 複数の問題を 1 つにまとめて返す

DTO と業務例外の作成(事前準備)

src/main/java/dev/mikoto2000/springboot/rfc9457/ に次のファイルを作成します。

TaskRequest.java
package dev.mikoto2000.springboot.rfc9457;

import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;

public record TaskRequest(
    @NotBlank(message = "title は必須です")
    @Size(max = 50, message = "title は 50 文字以内です")
    String title,
    @NotBlank(message = "assignee は必須です")
    String assignee) {}
Task.java
package dev.mikoto2000.springboot.rfc9457;

public record Task(String id, String title, String assignee, boolean completed) {}
TaskNotFoundException.java
package dev.mikoto2000.springboot.rfc9457;

public class TaskNotFoundException extends RuntimeException {
  public TaskNotFoundException(String id) {
    super(id);
  }
}
TaskAlreadyCompletedException.java
package dev.mikoto2000.springboot.rfc9457;

public class TaskAlreadyCompletedException extends RuntimeException {
  public TaskAlreadyCompletedException(String id) {
    super(id);
  }
}

例外は失敗の意味だけを持ちます。HTTP ステータスや応答の文章は、次のハンドラーで決めます。

Service と Controller の作成(事前準備)

TaskService.java
package dev.mikoto2000.springboot.rfc9457;

import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentMap;
import java.util.concurrent.atomic.AtomicLong;
import org.springframework.stereotype.Service;

@Service
public class TaskService {
  private final ConcurrentMap<String, Task> tasks = new ConcurrentHashMap<>();
  private final AtomicLong lastTaskId = new AtomicLong(2);

  public TaskService() {
    tasks.put("t1", new Task("t1", "資料を読む", "alice", false));
    tasks.put("t2", new Task("t2", "レビューする", "bob", true));
  }

  public Task find(String id) {
    Task task = tasks.get(id);
    if (task == null) {
      throw new TaskNotFoundException(id);
    }
    return task;
  }

  public Task create(TaskRequest request) {
    String id = "t" + lastTaskId.incrementAndGet();
    Task task = new Task(id, request.title(), request.assignee(), false);
    tasks.put(id, task);
    return task;
  }

  public Task complete(String id) {
    return tasks.compute(id, (key, task) -> {
      if (task == null) {
        throw new TaskNotFoundException(key);
      }
      if (task.completed()) {
        throw new TaskAlreadyCompletedException(key);
      }
      return new Task(task.id(), task.title(), task.assignee(), true);
    });
  }
}

ConcurrentHashMap.compute の中で、同じ ID の状態確認と更新を原子的に行います。 同じタスクへの完了リクエストが重なっても、成功するのは 1 件です。それ以外は完了済みの例外となり、パターン2で 409 に変換します。 存在しないタスクでは、更新前と同じく未検出の例外を返します。

TaskController.java
package dev.mikoto2000.springboot.rfc9457;

import jakarta.validation.Valid;
import java.net.URI;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/tasks")
public class TaskController {
  private final TaskService service;

  public TaskController(TaskService service) {
    this.service = service;
  }

  @GetMapping("/{id}")
  public Task get(@PathVariable String id) {
    return service.find(id);
  }

  @PostMapping
  public ResponseEntity<Task> create(@Valid @RequestBody TaskRequest request) {
    Task task = service.create(request);
    return ResponseEntity.created(URI.create("/tasks/" + task.id())).body(task);
  }

  @PostMapping("/{id}/complete")
  public Task complete(@PathVariable String id) {
    return service.complete(id);
  }
}

この時点ではハンドラーがないため、TaskNotFoundException は 500 になります。 アプリを起動し、別のターミナルから curl -i http://localhost:8080/tasks/t1 を実行して 200 が返れば事前準備は完了です。講義では、次のパターンから失敗の意味に合った応答へ変換します。

パターン1: 標準メンバーだけで返す

まず、RFC 9457 が定義する標準メンバーだけを使います。 アプリ固有の項目を足さず、HTTP ステータスの意味に任せる返し方です。

Pattern1ExceptionHandler.java
package dev.mikoto2000.springboot.rfc9457;

import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class Pattern1ExceptionHandler {
  @ExceptionHandler(TaskNotFoundException.class)
  public ProblemDetail notFound(TaskNotFoundException ex) {
    return ProblemDetail.forStatusAndDetail(
        HttpStatus.NOT_FOUND, "指定したタスクが見つかりません");
  }
}

@ExceptionHandler から ProblemDetail を返すと、instance はリクエストのパスで初期化されます。 title は、よく知られたステータスなら HttpStatus の理由句から設定されます。

アプリを起動して確認します。

curl -i http://localhost:8080/tasks/missing

404 と Content-Type: application/problem+json が返り、本文は次の形になります。

{
  "title": "Not Found",
  "status": 404,
  "detail": "指定したタスクが見つかりません",
  "instance": "/tasks/missing"
}

type がないことに注目してください。 RFC 9457 では、type がない場合は about:blank とみなします。 about:blank は「HTTP ステータス以上の意味を持たない」ことを表します。

Spring Framework 7 では ProblemDetail の type は既定で設定されません。 この教材の標準構成では、Spring の Jackson 用ミックスインが未設定の type を JSON 応答から省略します。 Spring Framework 6.2 以前は "type": "about:blank" が出力されていました。 どちらも RFC 9457 に適合しますが、JSON の見た目は変わります。

このパターンの利点は、契約が小さいことです。 利用者は HTTP ステータスと detail だけを見ればよく、独自の語彙を覚える必要がありません。

この例では forStatusAndDetail で説明を指定します。標準構成では、forStatus で生成して detail を設定しない場合、JSON 応答から detail が省略されます。 一方で、同じ 404 でも「タスクがない」のか「別の資源がない」のかを機械的に区別できません。

パターン2: 独自の type を定義する

次に、アプリ固有の問題種別を type で表します。 同じ 409 でも、何が競合したのかを機械的に区別できるようにします。

まず、完了済みタスクの 409 を標準メンバーだけで返してみます。Pattern2ExceptionHandler.java を作成します。

Pattern2ExceptionHandler.java(比較用)
package dev.mikoto2000.springboot.rfc9457;

import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class Pattern2ExceptionHandler {
  @ExceptionHandler(TaskAlreadyCompletedException.class)
  public ProblemDetail alreadyCompleted(TaskAlreadyCompletedException ex) {
    return ProblemDetail.forStatusAndDetail(
        HttpStatus.CONFLICT, "このタスクはすでに完了しています");
  }
}

アプリを再起動し、次を実行します。

curl -i -X POST http://localhost:8080/tasks/t2/complete

409 で type が省略され、クライアントは HTTP ステータスから競合と判断できます。将来、同じ 409 に別の競合が加わったとき、完了済みの場合だけ画面を更新するには何を見ればよいでしょうか。

同じファイルを次の完成版で置き換え、再起動後に同じリクエストを送ります。HTTP ステータスは 409 のままで、type を見れば完了済みの場合を識別できます。

Pattern2ExceptionHandler.java
package dev.mikoto2000.springboot.rfc9457;

import java.net.URI;
import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class Pattern2ExceptionHandler {
  private static final URI TASK_ALREADY_COMPLETED =
      URI.create("https://example.com/problems/task-already-completed");

  @ExceptionHandler(TaskAlreadyCompletedException.class)
  public ProblemDetail alreadyCompleted(TaskAlreadyCompletedException ex) {
    ProblemDetail body = ProblemDetail.forStatusAndDetail(
        HttpStatus.CONFLICT, "このタスクはすでに完了しています");
    body.setType(TASK_ALREADY_COMPLETED);
    body.setTitle("Task Already Completed");
    return body;
  }
}

type は問題の種類を表す URI 参照です。 同じ種類の失敗には、同じ type を返します。 title は種類の短い説明で、発生ごとに変えません。 個々の発生についての説明は detail に置きます。title はローカライズで変わることがあるため、クライアントが種別で分岐するときは type を使います。

curl -i -X POST http://localhost:8080/tasks/t2/complete

409 と次の本文が返ります。

{
  "type": "https://example.com/problems/task-already-completed",
  "title": "Task Already Completed",
  "status": 409,
  "detail": "このタスクはすでに完了しています",
  "instance": "/tasks/t2/complete"
}

type の URI は、自組織が管理する範囲のものを使います。 RFC 9457 は、問題の解決方法を説明する文書へ解決できることを推奨しています。 ただし、解決できない URI を使う場合の指針も示されています。 社内 API で文書を公開しない場合は、一意で安定していれば解決不能でも運用できます。 その場合も、type の値は勝手に変えないでください。

このパターンの利点は、利用者が type で分岐できることです。 detail の文章を解析する必要がありません。 一方で、type の一覧を API の契約として管理する必要があります。

パターン3: 複数の問題をまとめる

入力不正では、複数の項目が同時に違反します。 この場合は、1 つの入力検証エラーを表し、個々の違反を errors にまとめます。 この例で errors に含めるのは、getFieldErrors() が返す項目単位の違反です。DTO 全体に対する違反をまとめる場合は、getGlobalErrors() の結果も扱います。

Pattern3ExceptionHandler.java
package dev.mikoto2000.springboot.rfc9457;

import java.net.URI;
import java.util.List;
import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class Pattern3ExceptionHandler {
  private static final URI INVALID_INPUT =
      URI.create("https://example.com/problems/invalid-task-input");

  public record FieldProblem(String field, String message) {}

  @ExceptionHandler(MethodArgumentNotValidException.class)
  public ProblemDetail invalidInput(MethodArgumentNotValidException ex) {
    ProblemDetail body = ProblemDetail.forStatusAndDetail(
        HttpStatus.BAD_REQUEST, "入力内容を確認してください");
    body.setType(INVALID_INPUT);
    body.setTitle("Invalid Task Input");
    List<FieldProblem> errors = ex.getBindingResult().getFieldErrors().stream()
        .map(error -> new FieldProblem(error.getField(), error.getDefaultMessage()))
        .toList();
    body.setProperty("errors", errors);
    return body;
  }
}

errors は RFC 9457 の標準メンバーではなく、拡張メンバーです。 拡張メンバーは、problem type の定義の一部としてアプリが決めます。 この API では errors の各要素を field と message にします。RFC 9457 の例は pointer と detail を使っており、どちらの形も各 API が定める契約です。

curl -i -X POST http://localhost:8080/tasks \
  -H 'Content-Type: application/json' \
  -d '{"title":"","assignee":""}'

400 と次の本文が返ります。

{
  "type": "https://example.com/problems/invalid-task-input",
  "title": "Invalid Task Input",
  "status": 400,
  "detail": "入力内容を確認してください",
  "instance": "/tasks",
  "errors": [
    { "field": "title", "message": "title は必須です" },
    { "field": "assignee", "message": "assignee は必須です" }
  ]
}

ここで注意したいのは、まとめてよい範囲です。 同じ種類の問題が複数ある場合は、1 つの応答にまとめられます。 一方、種類の異なる問題が同時に起きた場合は、最も重要または緊急なものを 1 つ返すことを推奨しています。 種類の違う問題を無理に 1 つの応答へ詰め込むと、HTTP の意味と対応しにくくなります。

入力検証の複数違反は、すべて「入力が不正」という同じ種類です。 そのため errors にまとめるのは自然です。 「入力が不正」と「対象が存在しない」が同時に起きた場合は、どちらを返すかを決めてください。

3 つのパターンの比較

観点パターン1パターン2パターン3
独自 typeなし(about:blank)ありあり
拡張メンバーなしなしerrors
機械的な分岐ステータスのみtypetype と errors
契約の大きさ小さい中程度中程度
主な用途一般的な失敗業務固有の失敗入力検証

この教材ではパターンを分けて確認するため、Advice を 3 つに分けています。 実際のアプリでは 1 つの Advice にまとめてかまいません。 その場合も、問題種別ごとに type と拡張メンバーを一貫させてください。

MockMvc による契約の検証

この節は発展です。基本編では curl の結果を見て、3 つの形式でクライアントに伝わる情報を説明します。

pom.xml の dependencies に、次の依存関係があることを確認します。 JUnit と Mockito の基本は テスト入門 を参照してください。

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-webmvc-test</artifactId>
  <scope>test</scope>
</dependency>

次を src/test/java/dev/mikoto2000/springboot/rfc9457/Rfc9457ContractTest.java に配置します。

Rfc9457ContractTest.java
package dev.mikoto2000.springboot.rfc9457;

import static org.hamcrest.Matchers.hasSize;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.Mockito.when;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
import org.springframework.context.annotation.Import;
import org.springframework.http.MediaType;
import org.springframework.test.context.bean.override.mockito.MockitoBean;
import org.springframework.test.web.servlet.MockMvc;

@WebMvcTest(TaskController.class)
@Import({Pattern1ExceptionHandler.class, Pattern2ExceptionHandler.class,
    Pattern3ExceptionHandler.class})
class Rfc9457ContractTest {
  @Autowired
  MockMvc mvc;

  @MockitoBean
  TaskService service;

  @Test
  void missingTaskReturns404WithStandardMembersOnly() throws Exception {
    when(service.find("missing")).thenThrow(new TaskNotFoundException("missing"));
    mvc.perform(get("/tasks/missing"))
        .andExpect(status().isNotFound())
        .andExpect(content().contentTypeCompatibleWith(MediaType.APPLICATION_PROBLEM_JSON))
        .andExpect(jsonPath("$.status").value(404))
        .andExpect(jsonPath("$.title").value("Not Found"))
        .andExpect(jsonPath("$.instance").value("/tasks/missing"))
        .andExpect(jsonPath("$.type").doesNotExist());
  }

  @Test
  void alreadyCompletedReturns409WithProblemType() throws Exception {
    when(service.complete("t2")).thenThrow(new TaskAlreadyCompletedException("t2"));
    mvc.perform(post("/tasks/t2/complete"))
        .andExpect(status().isConflict())
        .andExpect(jsonPath("$.type")
            .value("https://example.com/problems/task-already-completed"))
        .andExpect(jsonPath("$.title").value("Task Already Completed"))
        .andExpect(jsonPath("$.status").value(409));
  }

  @Test
  void invalidInputReturnsErrorsExtension() throws Exception {
    mvc.perform(post("/tasks").contentType(MediaType.APPLICATION_JSON)
        .content("{\"title\":\"\",\"assignee\":\"\"}"))
        .andExpect(status().isBadRequest())
        .andExpect(jsonPath("$.status").value(400))
        .andExpect(jsonPath("$.type").value("https://example.com/problems/invalid-task-input"))
        .andExpect(jsonPath("$.errors", hasSize(2)))
        .andExpect(jsonPath("$.errors[0].field").exists())
        .andExpect(jsonPath("$.errors[0].message").exists());
  }
}

$.type の検証は、使う Spring Framework の版で変わります。 Spring Framework 7 では type が省略されるため、存在しないことを検証します。 Spring Framework 6.2 以前では about:blank が出力されるため、その値を検証してください。

errors の順序は保証されません。 件数と、各要素に必要な項目があることを確認します。 メッセージの完全な文章を成功条件にしないでください。 ロケールや制約の変更で変わります。

練習

  1. パターン2 の type を、存在しないタスクの 404 にも付けてみましょう。 about:blank を使う場合と、独自の種類を使う場合で、利用者の分岐がどう変わるかを比べてください。
  2. パターン3 の errors に、拒否した値そのものを含めるべきか考えてみましょう。 入力値をそのまま返すと、ログや画面に機密情報を残すおそれがある。
  3. 同じ 409 でも「すでに完了」と「名前の重複」が起きた場合、どちらを返すかを決めてください。

座学で学ぶ RFC 9457 エラー返却

RFC 9457 の位置づけと標準メンバー

RFC 9457 は「Problem Details for HTTP APIs」という仕様です。 2023 年 7 月に公開され、RFC 7807 を置き換えました。 HTTP API のエラーを表す共通形式を定義し、API ごとに新しい形式を作らなくて済むようにします。

仕様が定義する標準メンバーは 5 つです。 すべて省略可能で、必須の項目はありません。

メンバー型役割
typeURI 参照問題の種類を識別する
title文字列問題の種類の短い説明
status整数この発生の HTTP ステータス
detail文字列この発生の説明
instanceURI 参照この発生を識別する URI

type と title は「種類」の情報です。 同じ種類の失敗では、同じ値を使います。 status、detail、instance は「今回の発生」の情報です。 個々の発生についての情報で、別の発生でも同じ値を取ることがあります。たとえば、同じ種類の競合が繰り返されても status は 409 です。

この区別が設計の出発点になります。 detail に種類の情報を詰め込むと、利用者は文章を解析する必要が出てきます。 種類は type で表し、detail は人間向けの補足に留めるのが基本です。

type を省略した場合は about:blank とみなされます。 about:blank は「HTTP ステータス以上の意味を持たない」ことを表します。 この場合、title は HTTP ステータスの理由句と同じにすることが推奨されています。

type の設計

type は URI 参照です。 可能なら絶対 URI を使います。相対 URI は応答の基準 URI から解決されるため、同じ文字列でも異なる種別として解釈されることがあります。 重要なのは、同じ問題には同じ値を使い、値を勝手に変えないことです。

RFC 9457 は、type の URI が問題の解決方法を説明する文書へ解決できることを推奨しています。 ただし、解決できない URI を使う場合の指針も示しています。 社内 API のように文書を公開しない場合でも、一意で安定していれば運用できます。

type を設計するときは、次の点を決めておきます。

  • どの失敗を 1 つの種類としてまとめるか
  • 種類ごとに、どの拡張メンバーを伴うか
  • type の値を変更する場合の互換性の扱い

type の一覧は API の契約です。 利用者が type で分岐するなら、値を追加しても既存の値は変えないでください。

発展: problem type の登録

IANA の「HTTP Problem Types」レジストリには about:blank などが登録されています。広く使われる種類を設計するときは、登録済みの種別も確認します。

複数問題の扱いと拡張メンバー

RFC 9457 は、複数の問題をどう扱うかについても指針を示しています。 同じ種類の問題が複数ある場合は、1 つの応答にまとめられます。 入力検証の複数違反がこれにあたります。

一方、種類の異なる問題が同時に起きた場合は、最も重要または緊急なものを 1 つ返すことが推奨されています。 複数の異なる種類を 1 つの応答に詰め込む「batch」形式は、HTTP の意味と対応しにくいとされています。

拡張メンバーは、problem type の定義の一部として追加します。 標準メンバーと同じ名前を使うと意味が衝突するため、避けてください。 RFC 9457 自身も、入力検証の例で errors という拡張を使っています。

拡張メンバーを設計するときは、次を決めておきます。

  • 名前と型
  • どの problem type で伴うか
  • 省略可能か、必須か
  • 値を追加した場合の互換性

拡張メンバーはアプリの契約です。 標準メンバーではないため、利用者には API の文書で伝える必要があります。

application/problem+json と content negotiation(発展)

Problem Details を JSON で返すときのメディアタイプは application/problem+json です。 XML の場合は application/problem+xml です。

Spring Framework では、Jackson の JSON コーデックが ProblemDetail に対して application/problem+json を生成可能なメディアタイプとして扱います。 そのため、content negotiation で優先されます。

利用者側は、本文を読む前に Content-Type を確認してください。 JSON はどのオブジェクトも Problem Details の形に見えることがあります。 Content-Type が application/problem+json であることが、Problem Details であることの手がかりになります。

Accept ヘッダーで application/problem+json を指定しない場合でも、エラー応答はこの形式で返ることがあります。 クライアントの実装では、エラー応答の Content-Type を決め打ちしないでください。

契約としてのエラー応答とセキュリティ

エラー応答は API の契約です。 正常系と同じように、テストで確認します。

検証する項目は、ステータス、Content-Type、標準メンバー、拡張メンバーです。 detail の完全な文章や instance の具体的な値に、依存しすぎないでください。

セキュリティでは、応答に含める情報を絞ります。 detail に SQL、接続情報、クラス名、スタックトレースを含めないでください。 拡張メンバーも同じです。 入力値をそのまま返すと、機密情報が応答やログに残る可能性があります。

想定外の失敗では、固定した detail と調査用の ID を返します。 原因はサーバーのログに記録し、応答とは分けます。 この考え方は 例外処理・エラー応答入門 で扱っています。

type の URI を外部に公開する場合、その文書に内部情報を書かないようにします。 問題の解決方法を説明する文書は、利用者が読む前提で書きます。

既存資料との使い分け

バリデーション入門 は項目別の errors、バリデーションテスト は code・message・errors を持つ独自 DTO を使います。この章と例外処理の章では、RFC 9457 の標準メンバーを持つ ProblemDetail を使います。

例外処理・エラー応答入門 は、Advice で例外を HTTP 応答へ変換する実装が中心です。 この資料は、その応答を RFC 9457 の仕様に沿ってどう設計するかが中心です。

観点例外処理・エラー応答入門この資料
主な関心例外から応答への変換応答形式の設計
Advice の作り方詳しく扱う前提とする
標準メンバー一覧と使い方を確認種類と発生の区別を設計
type省略して about:blank とみなす独自の種類を定義する
問題種別の識別子アプリ固有の code独自 type を定義した応答では、その URI
複数問題errors の実装まとめてよい範囲を判断

独自の problem type を定義したら、クライアントは type の URI を問題種別の主識別子として使います。既存クライアントが code に依存する場合は、対応する値を拡張メンバーとして返し続けられます。

まず実装を学びたい場合は 例外処理・エラー応答入門 から読んでください。 応答形式を設計したい場合は、この資料の座学から読むと判断材料が揃います。

まとめ

  • RFC 9457 は HTTP API のエラー形式を定義し、RFC 7807 を置き換えた。
  • 標準メンバーは type、title、status、detail、instance の 5 つで、すべて省略可能。
  • type と title は種類、status、detail、instance は発生の情報。
  • type を省略すると about:blank とみなされ、HTTP ステータス以上の意味を持たない。
  • 同じ種類の複数問題はまとめられ、異なる種類は最も重要な 1 つを返すことが推奨される。
  • 拡張メンバーは problem type の定義の一部として、アプリの契約になる。
  • 応答は application/problem+json で返し、Content-Type を確認して扱う。
  • エラー応答も契約としてテストし、内部情報を含めない。

参考資料