llm-wiki/raw/official-docs/spring-mvc-rest-exception-handling.md

title, source_type, url, archive_url, vendor, related_branches, related_projects, tags, status, confidence, created, last_reviewed

title	source_type	url	archive_url	vendor	related_branches	related_projects	tags	status	confidence	created	last_reviewed
Spring Framework Reference — Exceptions (Spring MVC REST)	official-doc	https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-ann-rest-exceptions.html		VMware / Broadcom (Spring)	feature-boundary-validation-mapping-contract feature-business-rule-validation-contract	ca-skeleton	official-doc ca-tmpl error-handling spring-mvc	raw	high	2026-05-28	2026-05-28

Spring Framework Reference — Exceptions (Spring MVC REST)

Layer: raw/ — 외부 자료(공식 문서)의 원문 발췌·출처 기록. 검증된 요약은 /ingest 후 wiki/concepts/ 에 source-summary-template 형식으로 별도 작성. 원본은 raw 에 영구 보관.

Parent / 활용 branch

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-boundary-validation-mapping-contract	Mapper / deserialization 실패의 error category 분류 결정 (블라인드 B3). HttpMessageNotReadableException → VALIDATION 으로의 매핑 근거. ResponseEntityExceptionHandler 가 normative 하게 처리하는 예외 목록 확인
raw/branch-notes/feature-business-rule-validation-contract	MethodArgumentNotValidException (Bean Validation 실패) 의 HTTP 400 매핑 및 ErrorResponse 계약 근거

출처 / Source

• 원본 URL: https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-ann-rest-exceptions.html
• 아카이브 URL: (미제공)
• 저자 / 조직: Spring Framework 공식 문서 (VMware / Broadcom)
• 발행일: (지속 갱신 — 확인 시점 버전 7.0.7)
• 마지막 확인일: 2026-05-28

왜 저장했는지 / Why archived

feature-boundary-validation-mapping-contract 에서 블라인드 B3 로 식별된 문제 — mapper 가 던지는 예외(IllegalArgumentException, MapStruct NPE, record canonical constructor IllegalStateException)와 HttpMessageNotReadableException 같은 Spring 내장 deserialization 예외의 error category(VALIDATION vs INTERNAL) 분류 근거가 없었다. 본 공식 문서는 Spring MVC 가 normative 하게 어떤 예외를 어떻게 처리하는지, ErrorResponse 계약이 무엇인지, ResponseEntityExceptionHandler 가 다루는 예외 목록을 직접 정의하므로 이 분류 결정의 primary 근거 자료로 보관한다.

핵심 인용 / Key quotes (verbatim)

[§ Error Responses — main abstractions] "ErrorResponse — contract to expose HTTP error response details including HTTP status, response headers, and a body in the format of RFC 9457; this allows exceptions to encapsulate and expose the details of how they map to an HTTP response. All Spring MVC exceptions implement this."

[§ Error Responses — main abstractions] "ResponseEntityExceptionHandler — convenient base class for an @ControllerAdvice that handles all Spring MVC exceptions, and any ErrorResponseException , and renders an error response with a body."

[§ Error Responses — main abstractions] "ErrorResponseException — basic ErrorResponse implementation that others can use as a convenient base class."

[§ Error Responses — Render] "To enable RFC 9457 responses for Spring MVC exceptions and for any ErrorResponseException , extend ResponseEntityExceptionHandler and declare it as an @ControllerAdvice in Spring configuration. The handler has an @ExceptionHandler method that handles any ErrorResponse exception, which includes all built-in web exceptions. You can add more exception handling methods, and use a protected method to map any exception to a ProblemDetail ."

[§ Error Responses — Spring Boot note] "In Spring Boot, the spring.mvc.problemdetails.enabled property autoconfigures a ResponseEntityExceptionHandler that handles built-in exceptions with problem details."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
SPRING-MVC-EXC-C1	ErrorResponse 는 HTTP error response 의 status / headers / body(RFC 9457 형식) 를 노출하는 계약이며, 모든 Spring MVC 내장 예외가 이를 구현한다	[§ main abstractions] "contract to expose HTTP error response details including HTTP status, response headers, and a body in the format of RFC 9457 [...] All Spring MVC exceptions implement this."	official-vendor-doc	Spring Framework 6.x / 7.x 의 모든 Spring MVC 내장 예외	사용자 정의 예외(IllegalArgumentException, mapper NPE 등)가 자동으로 ErrorResponse 를 구현한다는 것은 증명하지 않음
SPRING-MVC-EXC-C2	ResponseEntityExceptionHandler 는 @ControllerAdvice 의 편의 base class 로, 모든 Spring MVC 예외 + ErrorResponseException 을 처리하고 body 가 있는 error response 를 렌더링한다	[§ main abstractions] "convenient base class for an @ControllerAdvice that handles all Spring MVC exceptions, and any ErrorResponseException , and renders an error response with a body."	official-vendor-doc	ResponseEntityExceptionHandler 를 extends 하는 @ControllerAdvice	사용자 정의 예외(IllegalArgumentException 등)를 자동 처리한다는 것은 증명하지 않음 — 별도 @ExceptionHandler 필요
SPRING-MVC-EXC-C3	RFC 9457 응답을 활성화하려면 ResponseEntityExceptionHandler 를 extends 하고 @ControllerAdvice 로 선언해야 하며, 이 handler 의 @ExceptionHandler 메서드는 모든 built-in web exception 을 포함하는 모든 ErrorResponse 예외를 처리한다	[§ Render] "extend ResponseEntityExceptionHandler and declare it as an @ControllerAdvice in Spring configuration. The handler has an @ExceptionHandler method that handles any ErrorResponse exception, which includes all built-in web exceptions."	official-vendor-doc	Spring Framework 6.x / 7.x + @ControllerAdvice 구성	@ExceptionHandler 의 controller-local vs global 우선순위는 본 인용이 직접 명시하지 않음 (Spring docs 다른 섹션 "Exceptions" 참조 필요)
SPRING-MVC-EXC-C4	HttpMessageNotReadableException 은 Spring MVC 가 ResponseEntityExceptionHandler 를 통해 normative 하게 처리하는 예외 목록에 포함되며, i18n message code 를 통해 커스터마이즈 가능하다	[§ Customization and i18n — table] HttpMessageNotReadableException → message code (default) (표에서 직접 나열됨, line 1997 in fetched text)	official-vendor-doc	Spring MVC 의 ResponseEntityExceptionHandler + HttpMessageNotReadableException	HTTP status code(400 Bad Request)는 본 "Error Responses" 페이지의 message code 표에서 명시적으로 나열되지 않음 — HTTP status 는 HttpMessageNotReadableException 의 ErrorResponse 구현 내부(Spring source)에서 정의됨
SPRING-MVC-EXC-C5	MethodArgumentNotValidException 은 Spring MVC 가 ResponseEntityExceptionHandler 를 통해 normative 하게 처리하는 예외 목록에 포함되며, message code arguments 로 {0} global errors list 와 {1} field errors list 를 제공한다	[§ Customization and i18n — table] "MethodArgumentNotValidException (default) {0} the list of global errors, {1} the list of field errors. Message codes and arguments for each error are also resolved via MessageSource ."	official-vendor-doc	Spring MVC Bean Validation (@Valid / @Validated) 처리	HTTP status code(400 Bad Request) 는 MethodArgumentNotValidException 의 ErrorResponse 구현 내부에서 정의됨 — 본 페이지에서 직접 명시되지 않음

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:

  • SPRING-MVC-EXC-C1: 모든 Spring MVC 내장 예외(including HttpMessageNotReadableException, MethodArgumentNotValidException)는 ErrorResponse 를 구현하며, Spring 이 RFC 9457 형식으로 error response 를 렌더링할 수 있다
  • SPRING-MVC-EXC-C2: ResponseEntityExceptionHandler 가 모든 Spring MVC 내장 예외와 ErrorResponseException 을 기본 처리한다
  • SPRING-MVC-EXC-C3: @ControllerAdvice + ResponseEntityExceptionHandler extends 가 RFC 9457 응답의 normative 활성화 방법이다
  • SPRING-MVC-EXC-C4: HttpMessageNotReadableException 은 Spring MVC normative exception handling 목록에 있다
  • SPRING-MVC-EXC-C5: MethodArgumentNotValidException 은 Spring MVC normative exception handling 목록에 있다

• 이 자료가 증명하지 않는 것:

  • 사용자 정의 예외(IllegalArgumentException, mapper NPE, record constructor IllegalStateException)가 자동으로 VALIDATION 또는 INTERNAL 카테고리로 분류된다는 것 — Spring 은 이들을 기본 처리하지 않음
  • HttpMessageNotReadableException 의 정확한 HTTP status code(400) — 이는 Spring source 의 ErrorResponse 구현에 있으며 별도 확인 필요
  • mapper layer 에서 발생하는 예외(MapStruct NPE, IllegalArgumentException)의 올바른 error category(MAPPING_FAILED / VALIDATION / INTERNAL) — 이 분류는 ca-tmpl 의 자체 operational contract 결정이며 본 Spring 문서가 직접 권고하지 않음
  • @ExceptionHandler 의 controller-local vs @ControllerAdvice global 해석 우선순위 — 본 페이지에서 다루지 않음

• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:

  • ca-tmpl 의 custom envelope 을 사용할 경우 spring.mvc.problemdetails.enabled=false 명시 여부 (SPRING-MVC-EXC-C5 및 Claims To Verify 항목과 연결)
  • mapper 에서 발생하는 IllegalArgumentException / IllegalStateException 에 대한 별도 @ExceptionHandler 또는 ErrorResponseException wrap 여부 결정 (B3 블라인드 해소를 위한 operational contract 결정)

메모 / Notes

• 본 페이지 URL (/mvc-ann-rest-exceptions.html) 은 Spring Framework 7.0.7 기준. 6.x 에서도 동일 경로이나 버전 간 미묘한 차이 있을 수 있음 — spring.mvc.problemdetails.enabled 는 Spring Boot 3.x (= Spring Framework 6.x) 에서 도입됨.
• HttpMessageNotReadableException 의 HTTP status(400) 를 직접 확인하려면 Spring source org.springframework.web.server.ResponseStatusException 계층 또는 HttpMessageNotReadableException.getStatusCode() 확인 필요.
• B3 블라인드 해소 경로: HttpMessageNotReadableException → Spring 이 400 으로 처리 (ErrorResponse 구현체) → ca-tmpl 에서 VALIDATION 카테고리로 재분류 가능. mapper NPE / IllegalArgumentException → Spring 기본 처리 대상 아님 → ca-tmpl 에서 별도 @ExceptionHandler 추가 또는 INTERNAL / MAPPING_FAILED 카테고리 명시 결정 필요.
• 추가로 봐야 할 동일 출처 페이지: Spring MVC "Exceptions" 섹션 (/webmvc/mvc-controller/ann-exceptionhandler.html) — @ExceptionHandler scope 와 resolution order 상세

Related / 관련

• 같은 주제 다른 official-doc: raw/official-docs/spring-problem-detail (Spring ProblemDetail / RFC 9457 Spring 6 지원 — already archived)
• 같은 주제 다른 official-doc: raw/official-docs/problem-detail-rfc-7807 (IETF RFC 7807 원문 — already archived)
• 이 자료를 인용한 wiki 요약: wiki/concepts/spring-mvc-exception-handling (생성 시)