Telling callers what went wrong.
WHAT AN ERROR RESPONSE NEEDS
The right status code A machine-readable code A human-readable message Enough detail to fix it
WHY A SEPARATE MACHINE-READABLE CODE
Callers should branch on a stable code, not on message text.
WHY NOT MESSAGE TEXT
It changes, and it may be translated.
WHAT TO KEEP STABLE
The codes, permanently.
WHAT VALIDATION ERRORS SHOULD INCLUDE
Which field, and what was wrong with it.
WHY PER FIELD
It lets the caller show the problem in the right place.
WHAT FORMAT TO USE
The same structure for every error, without exception.
WHY
Callers write one handler.
WHAT TO INCLUDE FOR SUPPORT
A unique identifier for the occurrence.
WHY
It connects the caller's report to your logs precisely.
WHAT TO NEVER INCLUDE
Stack traces Internal paths Database errors verbatim Anything revealing internal structure
WHY
It is both confusing and a security disclosure.
WHAT TO RETURN FOR UNEXPECTED FAILURES
A generic message, with the identifier.
WHAT TO LOG
The full detail, internally.
WHAT TO DOCUMENT
Every error code, and what a caller should do about it.
