Implementing Error Handling Patterns
1. Error Response Standardization Pattern
| Field | Detail |
|---|---|
| code | Machine-readable error code (string enum) |
| message | Human-readable summary |
| details | Field-level errors / context |
| traceId | For support correlation |
| timestamp | ISO 8601 UTC |
| documentation_url | Link to error reference |
2. Problem Details Pattern
| Field (RFC 9457) | Purpose |
|---|---|
| type | URI identifying problem type |
| title | Short summary |
| status | HTTP status |
| detail | Specific occurrence info |
| instance | URI of this occurrence |
| Content-Type | application/problem+json |
Example: Problem Details Response
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json
{
"type": "https://api.shop.com/problems/validation",
"title": "Validation Failed",
"status": 422,
"detail": "Order must contain at least 1 item",
"instance": "/orders/req_a8f2",
"errors": [{ "field": "items", "code": "min_size", "min": 1 }]
}3. Error Code Pattern
| Code Style | Example |
|---|---|
| Hierarchical String | order.payment.declined |
| Numeric | 40012 (HTTP-style 5-digit) |
| Service Prefix | ORDER-1042 |
| Stable | Never reuse code; document deprecation |
4. Error Propagation Pattern
| Practice | Detail |
|---|---|
| Translate at Boundary | Map domain errors to HTTP/gRPC at edge |
| Preserve Cause | Original error wrapped (stack trace logged) |
| Don't Leak Internals | Don't expose stack traces / SQL to clients |
| Carry Trace ID | Always |
5. Fail Fast Pattern
| Aspect | Detail |
|---|---|
| Validate Early | Reject malformed input at entry |
| Reject Quickly | Return 4xx without downstream calls |
| Benefit | Saves resources; better UX |
6. Fail Silent Pattern
| Use When | Detail |
|---|---|
| Non-Critical Path | Telemetry, optional enrichment |
| Background Refresh | Cache refresh failure → keep stale |
| Always | Log internally; never silently drop user-visible errors |
7. Default Response Pattern
| Strategy | Example |
|---|---|
| Empty Default | Return [] when search fails |
| Cached Default | Return last-good response |
| Static Stub | Hardcoded safe fallback |
| Partial | Return whatever succeeded |
8. Error Recovery Pattern
| Mechanism | Detail |
|---|---|
| Retry | Transient errors with backoff |
| Failover | Switch to secondary |
| Compensate | Undo prior side-effects |
| Graceful Degradation | Reduced feature mode |
| Manual Recovery | DLQ + ops console |
9. Compensating Action Pattern
| Aspect | Detail |
|---|---|
| Definition | Specific action that undoes a prior side-effect |
| Examples | Refund, release reservation, send correction email |
| Idempotent | Required (compensations may retry) |
| Logged | For audit and forensics |
10. Error Callback Pattern
| Aspect | Detail |
|---|---|
| Mechanism | Async failure notified via callback URL / event |
| Examples | Webhook for failed batch job, error topic |
| Includes | Job ID, error code, retry instructions |
| Security | Sign callbacks (HMAC) to prove origin |