Error classification
| Class | HTTP | Retry? | Action | | --- | --- | --- | --- | | Authentication | 401 | No | Validate key and header | | Validation | 422 | No | Correct payload schema | | Throttling | 429 | Yes | Backoff and retry | | Availability | 503 | Yes | Retry with idempotency |
Retry strategy
- Exponential backoff with jitter.
- Respect retry headers when present.
- Keep a max retry cap to avoid queue pileups.
Idempotency
Provide idempotency keys for replayed write operations to prevent duplicates in downstream systems.