Treat API errors as structured integration states. Persist the HTTP status, error code
and request ID rather than turning every non-2xx response into a blind retry.
Status
Meaning
Action
400
Request validation failed
Correct the request.
401
Credential missing or invalid
Check environment and credential.
403
Scope or source policy denied
Do not retry unchanged.
409
State conflict or capability unavailable
Inspect current resource state.
429
Application rate limit reached
Back off before retrying.
Uncertain write outcomes
Keep the original idempotency key and reconcile the existing operation. A new key can
represent a second logical write.
For integration support, send the request ID, endpoint and UTC timestamp to
[email protected].
