REST Error Envelope Design

An error envelope is a contract, not a convenience. Once a client ships, every field in your error response is something they're parsing.

The envelope I default to

• RFC 7807 application/problem+json — type, title, status, detail, instance, plus extensions
• First-class in Spring 6 and Boot 3 via ProblemDetail
• The type URI doubles as a link to docs, which shortens support cycles

What must be in the envelope

• A stable machine-readable code — never the HTTP status, because multiple codes share a status
• A traceId — every error I respond with correlates with APM and logs
• An instance — URI of the request for reproducibility
• For validation, an errors[] array with per-field {field, code, message}
• A human detail for developer tooling, never for end users

What never goes in

• Stack traces, SQL strings, internal paths — security leak and noise
• PII beyond what the caller already sent
• Tokens or secrets — even in rate-limit responses

Spring implementation

• Single @RestControllerAdvice with @ExceptionHandler for domain exceptions, handleMethodArgumentNotValid for bean validation, and a final @ExceptionHandler(Throwable.class) so nothing leaks unfiltered
• Extension fields via pd.setProperty("code", ...) and pd.setProperty("traceId", ...)

Stripe-flat as an alternative

• {error: {type, code, message, param}} — perfectly valid if applied universally
• The mistake is mixing RFC 7807 for some endpoints and Stripe-flat for others — clients can't write one error handler

Design mistakes I watch for

• A success: false flag — couples error semantics to a boolean, breaks HTTP expectations
• Status code as the only differentiator — clients can't tell VALIDATION_FAILED from BODY_MALFORMED
• Leaking org.hibernate.ConstraintViolationException: could not execute statement — the catch-all advice must translate
• Renaming envelope fields mid-lifecycle — treat the envelope as public contract, version accordingly
• Too many fine-grained codes nobody documents — start coarse, split when codes are client-actionable

Security subtleties

• Auth errors shouldn't reveal whether a username exists — one AUTH_INVALID_CREDENTIALS for both wrong-user and wrong-password
• Access-control errors sometimes need to be 404 not 403 to avoid leaking resource existence