Error Handling Patterns
Make backend failures diagnosable for engineers and understandable for API consumers.
Recommended approach
- Use consistent error shapes with stable machine-readable codes.
- Separate domain errors from infrastructure errors.
- Preserve stack traces and correlation IDs in logs.
Alternatives and when to choose them
- Framework default errors only for internal prototypes.
- Problem Details (RFC 9457 style) when API standardization is required across services.
Implementation checklist
- Define global exception mapping strategy.
- Document retryable vs non-retryable error codes.
- Ensure PII is not leaked in error payloads.
Common pitfalls
- Throwing raw infrastructure errors to API clients.
- Inconsistent status-code usage across modules.