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