Error Response Shapes
1 min read
Consistent error responses prevent clients from writing error handling as an afterthought.
Consistent error responses prevent clients from writing error handling as an afterthought.
How It Works
Error response design is often skipped in interviews, but it's 30% of real API quality. Every API needs a consistent error shape so clients can write one error handler, not one per endpoint. The canonical shape: { error: "human-readable message", code: "MACHINE_READABLE_CODE", details?: { field: "validation message" } }. Status codes matter: 400 for validation, 401 for auth, 403 for permissions, 404 for missing, 409 for conflicts, 429 for rate limits, 500+ for server errors. In interviews, sketch 2–3 error cases alongside your happy-path endpoints — it demonstrates you've thought about failure modes, not just the happy path.
Real-World Example
Stripe's error response is the gold standard: every error includes a
type(api_error, card_error, etc.), acode(card_declined, insufficient_funds), amessage(human-readable), and sometimes aparamfield pointing at the specific invalid input. Stripe's SDKs parse this shape uniformly, so client code looks the same regardless of which endpoint failed — dramatically simpler than ad-hoc error strings. Client integrations take hours instead of days because of this discipline.
Test Yourself
Scenario: You are designing the POST /charges endpoint for a payments service. List 4 distinct error cases a client might hit, and the HTTP status + error code + response body shape you would return for each.
Get notified when we launch
One email when the full practice product is live. No spam.