Handling HTTP 429 and Retry-After in API Clients
Respond to API rate limits with bounded waits, shared concurrency control and explicit request budgets, without creating a retry storm.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
HTTP 429 indicates that a request was rate limited under the service’s policy. A client should reduce pressure and follow documented retry guidance rather than immediately repeating every failed call.
Interpret the response contract
Retry-After can express a delay or an HTTP date when supplied. Parse the supported form, bound the wait and account for clock differences. Rate-limit scope can be per key, account or operation. Independent workers using the same credential need coordination; each worker staying below its own local limit may still exceed the shared budget.
Worked example: several workers collide
Five workers each retry ten requests immediately after a limit response. Their combined burst produces another limit response and repeats the cycle. A shared queue reduces concurrency, schedules eligible retries with jitter and stops when the operation’s total time or request budget is exhausted.
Test graceful exhaustion
Include a missing or malformed Retry-After, cancellation during a wait and a response that remains limited. Never retry forever. Preserve the original query range and identity so a resumed read does not silently become a new latest-state query. Expose a useful deferred or failed status when the budget is exhausted.
A practical acceptance test
Simulate several workers sharing one credential, all receiving 429. Verify a shared budget, bounded retry times and cancellation. Include both supported Retry-After forms plus a malformed value. The client must not start a simultaneous unlimited retry burst or silently switch the query to another key or network when its budget expires.
Questions about the topic
Frequently asked questions
Should every 429 be retried immediately?
No. Respect documented delay and shared request budgets.
Is per-worker throttling always sufficient?
No. Credentials or accounts can share limits across workers.
Standards & technical documentation