The idea
An error response should help a caller decide what to do next. Human-readable explanation and machine-readable classification serve different purposes. Keep a stable error code even when the wording changes for clarity or translation.
Design choice
Describe whether the caller can correct the request, retry later or seek operator help. Do not expose stack traces, credentials or internal database names. A temporary failure should not look like a permanently invalid customer action.
Worked example
Return a stable quota_exceeded code with a retry hint where appropriate. Show a concise explanation to the user and retain a separate internal diagnostic reference.
Before you ship
- Keep public codes stable
- Separate diagnostics from public messages
- Test retry and correction behaviour
Examples are illustrative. Adapt the checks to your own environment.