Communication

Make errors useful to the receiving system

Editorial edition · 16 November 2026

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.

Further reading

HTTP Semantics, RFC 9110

Search the library