- Purpose
- Make integration failures visible and recoverable.
- Prerequisites
- A queue or scheduler for retries
- Architecture
- 4xx are contract errors (do not retry blindly); 5xx and 429 are transient (retry with backoff).
Configuration
| Backoff | 1s, 2s, 4s, 8s, 16s with jitter; dead-letter after 5 attempts |
Implementation steps
- 01Classify the error
- 02Retry transient classes only
- 03Dead-letter with full context
- 04Alert on dead-letter depth
Examples
Error envelope
json
{ "error": { "code": "duplicate_assignment", "message": "An active assignment already exists.", "request_id": "req_01H8ZQF3" } }Testing procedure
- Force a 429 and confirm backoff, not a hot loop
Troubleshooting
Duplicate side effects after retry
Missing idempotency key on the write.