Read the stable error envelope
Every API error includes code and message. Gateway-backed requests also include requestId for correlation.
{
"code": "idempotency_conflict",
"message": "Idempotency-Key was used with a different request",
"requestId": "request_reference"
}
Classify before retrying
Retry network failures, 429, and selected 5xx responses with exponential backoff and jitter. Correct 4xx payload, scope, or ownership errors instead of retrying them.
- 401: replace or rotate the invalid credential
- 403: issue a key with the required scope
- 409: inspect idempotency or plan-limit code
- 429: wait for Retry-After
Keep one operation key
Generate an idempotency key when your business operation begins, persist it with that operation, and reuse it across every transport retry for 24 hours.