Resources · 77
API quotas: bound load and recover without a retry storm
Define budgets, counting identities and recovery behavior when a client reaches a limit.
· 9 min
What this guide helps achieve
- Define the limited resource
- Define overload behavior
- Bound recovery
- Exercise saturation and restoration
- Assign retry ownership
- Stop work that is no longer useful
Quick check
- Is HTTP 429 sufficient protection?
- Is Retry-After always a number?
- Can every request be retried automatically?
- Do three attempts per layer mean three overall?
- Does task expiry cancel its remote effect?
Step-by-step method
- 01
Define the limited resource
Separate request counts, transferred volume, compute cost and concurrent operations. Choose a counting identity and scope: client, account, route or service. Shared IP addresses can group independent people; per-user API keys alone cannot constrain aggregate cost.
Deliverable: unit, window and scope for each limit.
- 02
Define overload behavior
Specify rejection, queuing or reduced service. HTTP 429 describes too many requests; Retry-After may indicate a wait. Its absence does not justify immediate retry loops. Counters should reflect multiple instances and expensive routes.
Deliverable: responses and counting policy.
- 03
Bound recovery
Limit both attempts and total elapsed time. Spread retries using progressive delays and random variation. Honor the received delay and handle clock differences for HTTP dates. For external effects, first check whether an operation already completed and provide duplicate protection.
Deliverable: client recovery policy.
- 04
Exercise saturation and restoration
In an authorized environment test bursts, sustained load, shared-IP clients, multiple instances and counter outages. Verify availability of important tasks and prevent every client from retrying together after recovery. Measure justified rejections and legitimate users incorrectly blocked.
Deliverable: reproducible tests and tuning decision.
- 05
Assign retry ownership
Map application, SDK, proxy and dependencies with their automatic attempts. Choose the responsible layer and disable or coordinate extra retries under the contract. Count the initial attempt in the total budget. Retain the business operation ID and check uncertain effects before retrying a non-idempotent operation.
Retry map and total per-operation budget.
- 06
Stop work that is no longer useful
Define an end-to-end deadline covering waiting, connection and processing, accounting for actual client limits. Reject expired tasks before queue admission. Local cancellation does not establish server termination: reconcile its state. Test gradual traffic recovery without restarting every queue simultaneously.
Propagated deadline and stopping or reconciliation evidence.
Acceptance case to reproduce
Fictional example: these inputs describe no customer or observed result.
View case inputs
{
"http_status": 429,
"retry_after_seconds": 30,
"workers": 20,
"retry_budget": 3,
"retry_budget_scope": "per_worker_retries_excluding_initial_request",
"scheduling_example": {
"response_received_at_seconds": 0,
"illustrative_retry_seconds": [
30,
31,
32,
33,
34
],
"workers_per_second": 4,
"alternative_deadline_seconds": 25,
"total_attempts_if_all_retries_used": 80
}
}Expected decision
Respect the 30-second wait; stagger the 20 workers and bound the retry budget.
Twenty clients: spread retries and count attempts
Fictional example: 20 workers each receive a 429 response at +0 s with Retry-After: 30. These times illustrate one possible distribution, without guaranteeing server capacity. Each worker has 3 retries in addition to its initial request.
| Policy | Calculation or schedule | What changes |
|---|---|---|
| Simultaneous retry | 20 × 1 = 20 @ +30 s | Waiting 30 seconds respects the delay, but all 20 requests return together: the burst can recur. |
| Distributed retry | 4 × 5 = 20 @ +30…+34 s | Four requests per second for five seconds spread the 20 retries without reducing their number. This illustrative schedule is not a substitute for a backoff policy with jitter. |
| Deadline at 25 seconds | 25 s < 30 s → 0 | If the remaining time is shorter than the required 30 seconds, stop or defer according to the contract. Do not shorten the delay to meet the deadline. |
| Maximum budget | 20 × (1 + 3) = 80 | If every attempt is used, 20 initial requests plus 60 retries make 80 requests overall. The cap guarantees neither success nor safe repetition. |
Fictional variations to test
Retry-After contains an HTTP date, not seconds.
Interpret the documented format and check the clock. Record the calculated wait; do not replace the date with an arbitrary delay.
Each worker has its own retry budget.
Also calculate aggregate load. Coordinate the shared quota and spread retries to avoid another synchronised burst.
A response is missing after an operation with business effects.
Check authoritative state and the idempotency contract before replaying. A timeout does not show that execution never occurred.
Evidence to retain
- Received headers, delay format and clock used.
- Aggregate attempt budget and maximum duration.
- Operation identifier and reconciled outcome.
Additional reference : IETF — RFC 9110, Retry-After [EN]
Verification procedure
- Record quota scope and retry budget.
- Exhaust the quota only in an authorized test.
- Keep 429, Retry-After and bounded retry chronology. Distinguish technical throttling from the business result: an exhausted quota should not become a response reporting zero stock.
- In a simulation without external load, count attempts across four layers each capped at three total calls.
- Expire a fictional queued task and verify it does not start as a new operation.
- Gradually restore authorized work after a simulated outage and retain calls, deadlines and unique business results.
Reusable worksheet
Complete with your authorised observations. These fields are a working template, not observed results.
| Field | Information to record |
|---|---|
| Limit | Unit, window, identity and route |
| Exceedance | Response, delay and user message |
| Recovery | Attempt budget, duplicates and stopping |
| Evidence | Tested load, rejections and restoration |
APIs: prevent retries multiplying across layers
An application, SDK, proxy and service can each retry one call. In a fictional chain with four layers making three total attempts each, up to 81 calls reach the failing dependency. This method adds a shared budget and useful deadline to existing quota controls.
Worked example
Illustrative situation
Fictional example: a catalog synchronization receives 429 and every client immediately retries.
Decision and expected evidence
The client honors waiting time, spreads retries, retains a cursor and checks operations already applied.
Distinguish the mechanisms
| Mechanism | Purpose | Check or limitation |
|---|---|---|
| Rate limit | Bound arrivals within a window | May still allow slow, expensive work |
| Concurrency limit | Bound simultaneous processing | Does not bound monthly consumption alone |
| Consumption quota | Bound cumulative usage | Specify renewal and billed units |
Management indicators
| Indicator | What it measures | First action |
|---|---|---|
| Rejections | Rejected requests by route and identity | Separate abuse from legitimate clients |
| Useful retries | Attempts producing a unique result | Reduce loops and duplicates |
| Call amplification | Dependency calls / initial business operations in the same window | Separate total attempts, retries and planned subcalls |
| Expired work admitted | Tasks started after their useful deadline | Also observe queues, cancellation and already-started effects |
Common pitfalls
- May still allow slow, expensive work
- Does not bound monthly consumption alone
- Specify renewal and billed units
Frequently asked questions
Is HTTP 429 sufficient protection?
No. It describes rejection; cost, concurrency, queues and client behavior also require control.
Is Retry-After always a number?
No. HTTP allows delay seconds or an HTTP date. Clients should recognize both forms.
Can every request be retried automatically?
No. For a non-idempotent effect a lost response may conceal success. Recovery must check business state.
Do three attempts per layer mean three overall?
No. They can multiply. Four fictional layers with three total attempts each yield up to 3⁴ = 81 calls at the last dependency.
Does task expiry cancel its remote effect?
Not necessarily. It should prevent new obsolete work; a remote operation already started needs a state check and appropriate compensation if available.
Retry-After: waiting, budgets and retry decisions
Decide whether to retry after 429 or 503
A waiting period answers “when?”, not “may this operation be repeated?”. Before retrying, identify the intended effect, read the provider contract and bound total work. An error status or a lost response does not prove that no earlier attempt produced an effect.
Local teaching model with no request, timer, storage or real write. It considers one decision after 429 or 503 using six predefined headers. Dates are read at the fictional instant 22 October 2026, 10:00:00 UTC, assuming an accurate clock. This is neither a complete HTTP parser nor a Stripe client. Obsolete HTTP-date forms, clock skew, transport and SDK-specific policies are outside the calculation.
Twelve ways to read Retry-After
Durations are seconds. Absolute dates need an explicit clock policy; calculations here assume the stated accurate clock. Past dates become zero in this model without permitting an immediate loop. Integer syntax alone does not define a client’s numeric limits.
| Illustrative value | Reading within this scope | Interpretation decision |
|---|---|---|
30 | Non-negative decimal integer: wait 30 seconds after receipt. | This means seconds, not 30 milliseconds. |
0005 | The 1*DIGIT syntax accepts these digits: 5 seconds. | Do not treat the leading zero as octal. |
0 | A declared delay of zero seconds. | Local policy, budgets and permission to repeat still require checking. |
Thu, 22 Oct 2026 10:00:45 GMT | An HTTP date 45 seconds after the fictional receipt time. | Clock uncertainty must not be silently treated as certainty. |
Thu, 22 Oct 2026 09:59:50 GMT | A date 10 seconds in the past; the model uses zero server wait. | A past date requires neither negative waiting nor unlimited replay. |
Field absent | No server wait is supplied. | This model uses its selected local delay, not a normative default. |
1.5 | 1.5 does not meet integer delay-seconds syntax. | Do not silently round it and call the field valid. |
-1 | -1 is not a non-negative decimal integer for this field. | Do not interpret it as a special permission. |
30s | The s unit suffix is not part of delay-seconds syntax. | Seconds are already implied; 30s is not the form 30. |
30, 60 | Two comma-separated durations are not one valid Retry-After value. | Do not split every comma: a valid HTTP date itself contains one. |
Empty value | The field exists but contains neither expected form. | Keep absent and malformed values distinct in records. |
9999999999999999999999 | The digit string meets integer syntax but exceeds this model’s numeric bounds. | Record the local limit without claiming the RFC sets it; never truncate to retry sooner. |
Compare waiting, remaining budget and duplicate risk
Five parameters cover 144 combinations. Fictional policy: wait for the greater of an interpretable server delay and the already selected local delay, then reserve 10 seconds for one attempt. If the remaining budget is insufficient, stop this interactive retry without shortening the server wait. The reserve is not a measured duration and the selected local delay is not a jitter generator.
Teaching decision :
The selected operation type and budget allow considering a retry in this model. This proves neither success nor authorisation on a real service.
- Interpretable server wait
- 30 s
- Selected wait
- 30 s
- Attempt reserve
- 10 s
- Wait + reserve
- 40 s
- Budget margin
- 20 s
Absent or invalid field: this wait comes from local policy. A real API can require a different decision.
Eight reproducible cases
| Fictional situation | Relevant parameters | Decision and limit |
|---|---|---|
| 429, read and 30-second wait | 429 · 30 seconds Conforming GET read Remaining budget after receipt : 60 s | Retry candidate With 60 seconds remaining, 30 + 10 leaves a 20-second margin. |
| Waiting exceeds the budget | 429 · 30 seconds Conforming GET read Remaining budget after receipt : 20 s | Stop this retry With 20 seconds remaining, do not shorten 30 just to force an attempt. |
| Write with unknown contract | 503 · Future date: +45 seconds POST write: retry contract unverified Remaining budget after receipt : 60 s | Check business state Even positive margin does not validate repeating POST. |
| Write with verified contract | 503 · Future date: +45 seconds POST write: retry contract verified Remaining budget after receipt : 60 s | Retry candidate Verified contract is an assumption, not a test of your provider. |
| Invalid fractional value | 503 · Invalid value: 1.5 Conforming GET read Remaining budget after receipt : 20 s | Retry candidate The five-second fallback is a local teaching choice; retain the parse error. |
| Absent field, long local delay | 429 · Field absent Conforming GET read Remaining budget after receipt : 60 s | Retry candidate The 40-second delay comes from the client rather than the server. |
| HTTP date already passed | 503 · Past date: −10 seconds Conforming GET read Remaining budget after receipt : 20 s | Retry candidate The model retains a five-second local delay; the past date triggers no immediate call. |
| Zero does not remove the budget | 429 · 0 seconds Conforming GET read Remaining budget after receipt : 20 s | Stop this retry The 40-second local delay plus reserve exceed the 20 seconds remaining. |
Five distinctions that change client behaviour
| Reference point | Documented meaning | Practical limit |
|---|---|---|
| 429 | RFC 6585 describes too many requests within a period. Retry-After may be present; a 429 response must not be stored by a cache. | The RFC does not set the provider’s counted identity, window or algorithm. |
| 503 | Retry-After can indicate the expected duration of service unavailability. | A 5xx alone does not establish whether a write can be replayed. |
| HTTP idempotence | PUT, DELETE and safe methods are idempotent in their intended effect. | Responses and logs may differ. Controlled POST retries need an additional contract. |
| Retries at multiple layers | Client, SDK and proxy attempts can multiply load. | In a fictional three-layer example with three total attempts at each layer, one request can generate up to 3 × 3 × 3 = 27 calls at the last layer. |
| Jitter and budget | AWS describes spreading retries to avoid synchronised clients. | Randomness makes no write idempotent and replaces neither a deadline nor an attempt limit. |
Five items for retry acceptance evidence
- Method, route, contract version and logical operation identity; keep secrets out of keys and logs.
- Status, raw field, receipt time, interpretation and clock assumption.
- Selected delay, current attempt, remaining budget and the layer actually controlling retries.
- Known or unknown business state, retry key, associated context and parameters, and reconciliation evidence when needed.
- Verified final outcome and user behaviour: understandable waiting, retained input and no button that unintentionally recreates an operation.
Compare idempotency contracts →
Primary sources and limits
The RFCs define the cited HTTP elements. AWS describes design choices and Stripe documents its own APIs. Budgets, local waits, cases and diagrams are educational: they neither measure your service nor execute requests.
- IETF · RFC 9110 — Retry-After et idempotence HTTP · June 2022 · STD 97
§5.6.7; §9.2.2; §10.2.3; §15.6.4 - IETF · RFC 6585 — 429 Too Many Requests · April 2012 · Standards Track
§4 - AWS Builders’ Library · Timeouts, retries, and backoff with jitter · Published 2019-12-05; accessed 2026-10-22
Retries; jitter; timeout scope - Stripe · Idempotent requests · Documentation accessed 2026-10-22
API v1: saved results, parameters, key pruning, execution boundary - Stripe · API v2 overview — Idempotency · Documentation accessed 2026-10-22
POST/DELETE; same API and account/sandbox; 30-day replay window - Stripe · Advanced error handling · Documentation accessed 2026-10-22
Stripe-Should-Retry; status codes; idempotency
References reviewed
GraphQL: errors, lists and partial data
GraphQL cost and partial results: two separate checks
An authorized query can still be too costly; a partial response measures none of its resource consumption.
- Compare absent data, partial data and data: null.
- Keep the original path even when a parent becomes null.
- Test permissions, quotas and interface states separately.
Explore GraphQL responses and nullability →
GraphQL Specification · September 2025 · Published edition · September 2025
Official references
References consulted: . The method and worksheet propose checks to adapt to your context; they do not constitute certification.
- IETF — RFC 6585, HTTP 429
- IETF — RFC 9110, Retry-After
- AWS — Timeouts, retries, and backoff with jitter
- IETF — RFC 9110, Retry-After
- GraphQL Specification · September 2025
- IETF · RFC 9110 — Retry-After et idempotence HTTP
- IETF · RFC 6585 — 429 Too Many Requests
- Stripe · Idempotent requests
- Stripe · API v2 overview — Idempotency
- Stripe · Advanced error handling
