API error shapes your users never see (but feel)

Inconsistent error payloads force frontend developers to guess. Guessing produces vague toasts, duplicate bug reports, and longer support threads.

Pick a minimal envelope: machine code, human message, correlation id. Document three example failures and how UI should map them — including when to stay silent and retry.

Node Service Design spends a module on writing errors your future self thanks you for. The exercise is tedious; that is the point.

Remember: users should see calm language; logs can be noisy. Split the two deliberately.