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

Empty intelligence archive with dossiers and maps AI-generated editorial illustration

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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

PolicyCalculation or scheduleWhat changes
Simultaneous retry20 × 1 = 20 @ +30 sWaiting 30 seconds respects the delay, but all 20 requests return together: the burst can recur.
Distributed retry4 × 5 = 20 @ +30…+34 sFour 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 seconds25 s < 30 s → 0If 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 budget20 × (1 + 3) = 80If 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

  1. Record quota scope and retry budget.
  2. Exhaust the quota only in an authorized test.
  3. 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.
  4. In a simulation without external load, count attempts across four layers each capped at three total calls.
  5. Expire a fictional queued task and verify it does not start as a new operation.
  6. Gradually restore authorized work after a simulated outage and retain calls, deadlines and unique business results.

AWS — Timeouts, retries, and backoff with jitter

Reusable worksheet

Complete with your authorised observations. These fields are a working template, not observed results.

FieldInformation to record
LimitUnit, window, identity and route
ExceedanceResponse, delay and user message
RecoveryAttempt budget, duplicates and stopping
EvidenceTested 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

MechanismPurposeCheck or limitation
Rate limitBound arrivals within a windowMay still allow slow, expensive work
Concurrency limitBound simultaneous processingDoes not bound monthly consumption alone
Consumption quotaBound cumulative usageSpecify renewal and billed units

Management indicators

IndicatorWhat it measuresFirst action
RejectionsRejected requests by route and identitySeparate abuse from legitimate clients
Useful retriesAttempts producing a unique resultReduce loops and duplicates
Call amplificationDependency calls / initial business operations in the same windowSeparate total attempts, retries and planned subcalls
Expired work admittedTasks started after their useful deadlineAlso 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.

Fictional empty network laboratory with gateway appliances on a dark amber-lit workbench. AI-generated editorial illustration
Generated, people-free conceptual network laboratory from the editorial collection. It depicts neither real infrastructure nor a throughput test.

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.

Twelve ways to read Retry-After
Illustrative valueReading within this scopeInterpretation decision
30Non-negative decimal integer: wait 30 seconds after receipt.This means seconds, not 30 milliseconds.
0005The 1*DIGIT syntax accepts these digits: 5 seconds.Do not treat the leading zero as octal.
0A declared delay of zero seconds.Local policy, budgets and permission to repeat still require checking.
Thu, 22 Oct 2026 10:00:45 GMTAn 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 GMTA date 10 seconds in the past; the model uses zero server wait.A past date requires neither negative waiting nor unlimited replay.
Field absentNo server wait is supplied.This model uses its selected local delay, not a normative default.
1.51.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.
30sThe s unit suffix is not part of delay-seconds syntax.Seconds are already implied; 30s is not the form 30.
30, 60Two comma-separated durations are not one valid Retry-After value.Do not split every comma: a valid HTTP date itself contains one.
Empty valueThe field exists but contains neither expected form.Keep absent and malformed values distinct in records.
9999999999999999999999The 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 : Retry candidate

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

Eight reproducible cases

Eight reproducible cases
Fictional situationRelevant parametersDecision and limit
429, read and 30-second wait429 · 30 seconds

Conforming GET read

Remaining budget after receipt : 60 s
Already selected local delay : 5 s

Retry candidate

With 60 seconds remaining, 30 + 10 leaves a 20-second margin.

Waiting exceeds the budget429 · 30 seconds

Conforming GET read

Remaining budget after receipt : 20 s
Already selected local delay : 5 s

Stop this retry

With 20 seconds remaining, do not shorten 30 just to force an attempt.

Write with unknown contract503 · Future date: +45 seconds

POST write: retry contract unverified

Remaining budget after receipt : 60 s
Already selected local delay : 5 s

Check business state

Even positive margin does not validate repeating POST.

Write with verified contract503 · Future date: +45 seconds

POST write: retry contract verified

Remaining budget after receipt : 60 s
Already selected local delay : 5 s

Retry candidate

Verified contract is an assumption, not a test of your provider.

Invalid fractional value503 · Invalid value: 1.5

Conforming GET read

Remaining budget after receipt : 20 s
Already selected local delay : 5 s

Retry candidate

The five-second fallback is a local teaching choice; retain the parse error.

Absent field, long local delay429 · Field absent

Conforming GET read

Remaining budget after receipt : 60 s
Already selected local delay : 40 s

Retry candidate

The 40-second delay comes from the client rather than the server.

HTTP date already passed503 · Past date: −10 seconds

Conforming GET read

Remaining budget after receipt : 20 s
Already selected local delay : 5 s

Retry candidate

The model retains a five-second local delay; the past date triggers no immediate call.

Zero does not remove the budget429 · 0 seconds

Conforming GET read

Remaining budget after receipt : 20 s
Already selected local delay : 40 s

Stop this retry

The 40-second local delay plus reserve exceed the 20 seconds remaining.

Five distinctions that change client behaviour

Five distinctions that change client behaviour
Reference pointDocumented meaningPractical limit
429RFC 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.
503Retry-After can indicate the expected duration of service unavailability.A 5xx alone does not establish whether a write can be replayed.
HTTP idempotencePUT, 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 layersClient, 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 budgetAWS 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.

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.