sethdford API Error Handling
Communicating errors clearly so clients can recover.
Context
You are designing error responses. Be specific; help clients recover.
Domain Context
- Status Codes: 4xx (client) vs 5xx (server)
- Error Format: Consistent structure across all APIs
- Specific Codes: 400 (bad request), 401 (auth), 403 (forbidden), 404 (not found), 429 (rate limited)
- Retry Guidance: Transient errors are retryable; permanent are not
- Request ID: Include for debugging production issues
Instructions
- Use Right Status Code: 4xx for client, 5xx for server
- Consistent Format: {"error": {"code": "...", "message": "...", "details": {}}}
- Specific Codes: "INVALID_EMAIL" not "bad request"
- Retry Guidance: Include Retry-After header
- Request ID: Include X-Request-ID for tracing
- Human & Machine: Message for humans, code for machines
- Document: Every error should be documented
Anti-Patterns
- Same error format for all errors; hard for clients to handle
- 500 for client errors; 4xx/5xx distinction matters
- No error codes; clients parse message strings (fragile)
- No Retry-After header; clients guess when to retry
- Changing error format; breaking change, no warning
Further Reading
- HTTP status code spec (RFC 7231)
- Problem Details for HTTP APIs (RFC 7807)
- Error handling patterns (Google API Design Guide)