Error Model and Retries
Apply a normalized error model and retry matrix to prevent unsafe retries and improve reliability.
#Purpose
Defines error classes and retry decisions shared across all integration flows.
#Integration prerequisites
- Central error normalization layer maps endpoint-specific responses to shared classes.
- Retry policy library supports jittered backoff and max-attempt caps.
- Operations team receives alerts for repeated terminal classes.
#Request and response patterns
- Responses include status code, machine-readable error class, and request identifier.
- Client records normalized class and retry decision for each failure.
- Terminal classes trigger operator workflow instead of automatic retries.
#Lifecycle and state model
- Validation class: correct input before resubmission.
- Auth class: rotate/fix credentials and retry after resolution.
- Rate limit class: back off and retry with pacing control.
- Transient platform class: bounded retries with alerting.
- Compliance/policy class: manual review and escalation required.
#Error and failure taxonomy
- Input/validation errors.
- Authentication/authorization errors.
- Rate limit and quota errors.
- Transient dependency or infrastructure errors.
- Terminal policy/compliance errors.
#Retry and idempotency guidance
- Classify failure into normalized class before any retry action.
- Retry only retryable classes with exponential backoff and jitter.
- Preserve idempotency key and operation identity for all retries.
- Escalate after max attempts or repeated terminal failures.
#Observability and debugging entry points
- Failure distribution by normalized class and endpoint family.
- Retry success ratio and average attempts to recovery.
- Top terminal classes requiring product or policy intervention.