SA-301d · Module 3

Error Contract Design

4 min read

Error responses are the most consumed part of any API — because every consumer must handle them, and the quality of the error response determines whether the consumer can self-diagnose or must open a support ticket. A well-designed error contract reduces support volume, accelerates consumer debugging, and builds trust in the API's reliability. A poorly designed error contract turns every failure into a bilateral investigation.

Do This

  • Return a consistent error structure across all endpoints — code, message, details, and a documentation link
  • Use specific error codes that consumers can switch on — "INSUFFICIENT_BALANCE" not just "400"
  • Include remediation guidance in the error message — tell the consumer what to do, not just what went wrong

Avoid This

  • Return a raw exception message — it exposes internal implementation details and helps nobody
  • Use HTTP status codes as the only error information — 400 covers a hundred different problems
  • Return different error structures from different endpoints — inconsistency forces consumers to handle errors per-endpoint