How do you map domain failures to HTTP responses in a Spring API?

Keeps domain outcomes transport-neutral and maps not-found, conflict, invalid transition, and dependency failure at the web boundary.

1Say itAnswer out loud first

2CompareCompare with Core answer

3RefineRefine with Stronger and Advanced

TL;DR

The service layer returns or throws meaningful application outcomes without constructing ResponseEntity. The controller or global advice maps those outcomes to HTTP: missing resources may become 404, state conflicts 409, structurally invalid requests 400, and successful creation 201 with a location when appropriate. The mapping is explicit because the same application operation may later be called from messaging or a job. Error bodies use stable application codes in addition to status.

Full answer below

Practice focus

Separation of concerns, status semantics, stable error codes, ambiguity, and consistent exception advice.

Answer first

Answer path

Core answer first, then checkpoints toward a stronger answer.

Start
Core answer
Start here. This is the direct spoken answer to practice first.
Overview
The application describes what failed; the web adapter decides how that outcome appears over HTTP.
The service layer returns or throws meaningful application outcomes without constructing ResponseEntity. The controller or global advice maps those outcomes to HTTP: missing resources may become 404, state conflicts 409, structurally invalid requests 400, and successful creation 201 with a location when appropriate. The mapping is explicit because the same application operation may later be called from messaging or a job. Error bodies use stable application codes in addition to status.
Checkpoint
Stronger answer
Optional upgrade with examples, trade-offs, and sharper phrasing.
I distinguish client-correctable domain failure from an unexpected defect and from a downstream dependency failure. A database unique constraint can become a known conflict only when the violated constraint maps to a specific business rule; other database errors remain server failures. Authorization failures belong to the security boundary rather than being disguised as validation. Retries depend on the operation and failure, not merely whether the response is 5xx.

Review signals

Use these to catch weak phrasing, shallow reasoning, and risky claims.

Common mistakesCandidateCommon mistakesMistakes that weaken the answer or signal shallow understanding.Open details

Details

Returning ResponseEntity from domain services.
Mapping every database exception to conflict.
Using validation errors for authorization failures.

How do you map domain failures to HTTP responses in a Spring API?

Practice focus

Answer path

Overview

Review signals

Follow-up prompts

Continue the section

Tech stacks

Skill areas

Suggest an improvement

Found this answer useful?