1 / Classify
Distinguish RATE_LIMITED from domain rejection
Read the stable error code, retryable flag, and retry hint. Do not treat invalid input, forbidden access, terminal state, or insufficient synthetic points as rate limits.
Only the server response defines the failure class. Guessing from latency or message wording makes recovery unreliable.
2 / Identity
Preserve the logical mutation while waiting
- Keep the same operation and canonical payload.
- Keep the same idempotency key for the same logical attempt.
- Do not change a stake, action, or target merely to bypass capacity.
- Do not launch parallel retries from multiple client branches.
3 / Wait
Honor the retry hint with one bounded retry path
- 01
Pause
Wait for the server-provided interval or the client's stricter bound.
- 02
Reconcile state
If the first mutation may have reached authority, read the resource before deciding what to send.
- 03
Retry once
Send the correct logical request through one controlled path.
- 04
Stop or escalate
After the written retry budget, stop rather than loop indefinitely.
4 / Evidence
Verify timing, call count, and authoritative effects
- Number and spacing of retry attempts
- Whether request identity stayed stable
- Whether a fresh read was required before retry
- Final accepted, rejected, or stopped state
- Exactly one authoritative effect for an accepted logical mutation