Skip to content

Docsio v2 is out

See changelog
← Docsio Research

API documentation · Research synthesis

API rate-limit docs: the missing contract between workers

What GitHub, Stripe, Slack and AWS reveal about shared API capacity, concurrency and retries, with a proposed multi-worker documentation test matrix.

By Docsio Research14 min read

A rate-limit number does not tell an integration which workers share it, which queue should wait, or whether another tenant can keep moving. Good API documentation makes those boundaries explicit. This synthesis connects provider policies and HTTP semantics into a proposed capacity contract: identify shared consumers, separate request rate from concurrent work, explain response signals, assign retry ownership and define when queued work expires.

Key findings

  • HTTP 429 does not define the identity or counting scope of a limit. Those boundaries need a provider-specific explanation.

  • Provider policies differ: GitHub combines several constraints, Slack scopes Web API limits by method and workspace for an app, and Stripe distinguishes rate from concurrency failures.

  • Client configuration can create another shared boundary. AWS documents an adaptive limiter that can slow unrelated resources using the same client instance.

  • The proposed acceptance matrix checks coordination, isolation and expiry. It is a test design, not a claim that these providers or a sample integration were benchmarked.

How we researched this

We inspected seven original sources on November 22, 2026: two HTTP standards, rate-limit guides from GitHub, Stripe and Slack, and two AWS engineering or SDK references. We compared the documented scope of limits, units, response signals and client behavior, including exceptions to simple retry advice. This is a purposive desk synthesis, not a representative API survey or load test. Provider facts are cited; the capacity worksheet, fictional scenario and acceptance criteria are our proposed documentation method. Mutable guides are described as observed on the access date, not assigned inferred publication dates.

Start with who shares the limit, not just its size

Imagine a fictional integration that imports records for several customers. Each customer has a queue, several workers consume it, and an SDK sends the requests. A single-worker demonstration succeeds. After deployment, one busy customer receives throttling responses. The team pauses every worker because the guide says to slow down after a rate-limit error.

Did that protect a genuinely shared allowance, or unnecessarily stop unrelated customers? The number of requests allowed per minute cannot answer that question. Neither can a successful one-worker demo. The missing information is the identity of the shared limit and the relationship between that identity and the integration's queues.

RFC 6585 defines 429 but explicitly leaves user identification and request counting to the server. It allows, rather than requires, a Retry-After header. A generic explanation of the status therefore cannot establish whether two credentials, endpoints or processes share capacity. RFC 6585, section 4

We propose starting a rate-limit guide with a sentence that can be completed without reading implementation code:

This allowance is shared by [consumers], when accessing [operations or resources], within [environment and time basis]. Other applicable limits are [constraints].

Then add a concrete example with two workers. State whether both workers draw from the same allowance, whether adding a credential changes that relationship, and what happens when one receives a throttle signal. If the provider does not expose enough information to answer a question, label it unknown. A precise uncertainty is more useful than a guessed independence guarantee.

This does not require publishing an internal limiter algorithm. A provider can describe externally meaningful boundaries without disclosing its infrastructure. The reader needs a usable contract for coordinating calls, not a diagram of every internal queue.

For documentation owners, the editorial test is straightforward: can an engineer decide which work should wait, and explain why the other work may continue? If the answer requires assuming that every API key owns an independent allowance, the guide needs another example.

What GitHub, Slack and Stripe make explicit

The following comparison concerns selected documented behaviors as observed on November 22, 2026. It is not a complete quota catalog, a provider ranking or a promise of achievable throughput. Follow the linked guide and the particular operation's documentation before implementing a scheduler.

Provider and contextDocumented boundary or signalDocumentation lesson
GitHub REST APIUser-authenticated calls can share a personal allowance. Installation authentication has different rules.Explain authentication identity before presenting a quota number. GitHub
Slack Web APIWeb API limits follow the method, workspace and app.Show the scope of the pause, not just the waiting period. Slack
Stripe APIThe reason header distinguishes rate, concurrency and resource-specific limits.Route recovery by the documented signal rather than status alone. Stripe

GitHub documents a secondary-limit condition of no more than 100 concurrent requests shared across REST and GraphQL, alongside other secondary constraints. Some secondary reasons and point costs are undisclosed, and secondary limits can change without notice. An available primary allowance therefore does not promise that another request will avoid throttling. GitHub rate limits

Slack does not publish precise burst limits. Its Web API guidance explains a Retry-After pause for the affected method and workspace across the app's tokens. That is evidence for scoping this particular pause; it is not proof that other traffic is exempt from its own limits. Slack rate limits

Stripe identifies the limiter with its Stripe-Rate-Limited-Reason header. A 429 without it can have another cause, including a lock timeout; absence alone does not identify that cause. Stripe lists a global rate limit per account of 100 requests per second in live mode and 25 in sandboxes, with additional restrictions and exceptions. Its guide warns that sandbox testing is not a perfect proxy for live behavior. Those numbers describe that specific limiter, not an endpoint throughput benchmark. Stripe rate limits

The comparison supports a practical writing choice: lead with the boundary, then the value, then the exception. Readers copying only a headline number should still see what it counts. Put environment differences next to the value instead of hiding them in a testing appendix.

Separate rate, concurrent work and the queue budget

A useful capacity worksheet should distinguish three questions: how quickly requests may start, how many may remain active, and how long the application is willing to keep unfinished work. The first two describe different constraints; the third is a product decision. Combining them into a single field called "limit" makes it difficult to explain a slowdown.

The worksheet below is our proposed structure. It deliberately asks for evidence and unknowns rather than prescribing a particular database, limiter or queue implementation.

Contract fieldWhat to write downExample of evidence to attach
Consumer identityWhich accounts, apps, credentials, workers or resources share the allowanceProvider scope statement and an annotated two-worker example
Counting unitRequests, weighted operations, bytes, active operations or another stated unitThe exact operation or quota reference
Time basisWindow, reset signal or refill behavior, if documentedA response example with units and interpretation
Concurrent workApplicable in-flight boundary and what ends an occupied slotOperation lifecycle and concurrency policy
Overlapping constraintsGlobal, operation-specific and resource-specific rules that also applyA diagram or list showing the combination
Local queue policyPriority, expiry and treatment of delayed workAn application-owned decision, labeled separately
EnvironmentSandbox, production, account tier and SDK configurationThe tested configuration and known differences

For an illustrative arithmetic example, suppose starts are evenly spaced at ten requests per second and every request lasts exactly two seconds. After the pipeline fills, twenty requests can be active at once. If duration becomes four seconds with the same start rate, that becomes forty. These are invented assumptions and arithmetic, not observed provider performance or recommended settings. They show why a guide should not use a start-rate number as a substitute for an in-flight constraint.

Now add a queue. If a customer's import waits behind older work, it may become useless before it ever sends a request. Increasing its retry count does not fix that product problem. The guide should name whether expired work is discarded, held for manual restart, or rescheduled with the customer's consent. A delayed job and a failed HTTP request are different states.

Avoid turning the worksheet into a claim that a central scheduler is mandatory. A small single-process client and a distributed integration have different coordination needs. The documentation should make the assumptions visible so a reader knows when the simple example stops being sufficient.

Translate response signals into an explicit waiting policy

A timing field is useful only when its units and intended scope survive the journey into application code. RFC 9110 permits Retry-After to contain either an HTTP date or a non-negative integer number of seconds after receipt of the response. A parser that accepts only an integer implements only one form of the field. HTTP Semantics, section 10.2.3

For a general HTTP client, document both forms and test them. For a provider-specific guide, identify the form that provider promises, while making clear whether the example parser supports anything broader. Do not relabel an absolute reset timestamp as a duration just because both happen to be numbers.

We recommend describing the waiting decision in this order:

  1. Identify the provider error category and the affected scope.
  2. Interpret the documented timing signal and retain enough evidence to explain the decision.
  3. Check whether the operation remains eligible to run, including cancellation and expiry.
  4. Schedule eligible work according to the provider policy and the application's coordination rules.
  5. Report delayed, expired and failed outcomes separately.

These are proposed integration design steps, not additional requirements imposed by the HTTP standards. They also do not establish whether repeating a state-changing operation is safe. That belongs in the operation's recovery contract. Our API error documentation report covers that separate decision.

A useful deadline example is entirely hypothetical: a server asks a client to wait sixty seconds, but the application job has twenty seconds left. The guide should not suggest shortening the server's wait simply to fit the local deadline. Instead, specify whether the application stops the job or preserves it for a later, explicitly permitted attempt. Give the user a comprehensible result, such as "deferred until the next import window," only when the application actually supports that state.

Missing, malformed and unexpectedly distant timing values deserve examples too. Define the fallback and its owner. Avoid promising a universal safe delay for every API. Keep provider instructions separate from application safeguards so a future change to either can be reviewed without rewriting an unexplained magic number.

Finally, show what is stored when work waits: scope identifier, reason, next eligible time, overall expiry and attempt history. Use safe identifiers rather than credentials. This creates a record that can distinguish a deliberate pause from a stuck worker.

Document the SDK as another participant in the system

Retry behavior can exist below the code sample. AWS's engineering guidance describes how retries at multiple service layers can amplify load and discusses choosing a retry point for suitable low-cost operations. It also explains why jitter helps spread retry traffic. Those are design considerations, not proof that one retry arrangement fits every workflow. AWS engineering guidance

As accessed on November 22, 2026, the AWS SDK guide describes a useful boundary for applicable implementations: its adaptive limiter operates per client instance and can delay initial requests as well as retries. A throttled resource can therefore slow requests to other resources sharing that client. The page also says its updated behavior requires AWS_NEW_RETRIES_2026=true until it becomes the default, and its support table directs some SDKs to individual tracking issues. Do not apply that page's defaults to every installed version. AWS SDK retry behavior

The editorial implication is broader than one SDK. A capacity guide should record which layer controls each decision. Otherwise, an example that appears to make one attempt may be nested inside several independent retry policies.

Layer in a fictional integrationQuestion the guide should answerEvidence for the example
Application jobCan the entire task restart, and does it keep completed progress?Job lifecycle and restart rule
Queue workerDoes redelivery replay the same operation or resume a checkpoint?Worker configuration and failure example
HTTP client or SDKWhich failures trigger another transport attempt?Package version, retry mode and explicit configuration
Shared schedulerWhich consumers wait after one receives a throttle signal?Scope mapping and recorded decisions
User actionCan clicking retry create a second copy of pending work?UI state and duplicate-action handling

This table is a review aid, not a requirement to implement five layers. If a layer does not exist, say so. If the SDK owns transport retries, show how application-level restart logic avoids accidentally treating each SDK exhaustion as a fresh, unlimited task.

A shared client is not automatically wrong, and separate clients are not automatically right. The relevant question is whether the client's coordination boundary matches the workload's intended isolation. Splitting clients must not be presented as a way to escape a provider's shared allowance. It changes local behavior, not the provider's contract.

Include the settings with the example rather than relying on a reader's default environment. A small configuration note stating the tested package version, retry ownership and queue policy can be more useful than a longer code listing that silently inherits all three.

A proposed, unexecuted multi-worker test matrix

The following tests have not been executed for this report. They are proposed acceptance checks for teams publishing an integration guide. Use deterministic local fixtures or a permitted test environment. Do not discover undocumented thresholds by flooding a production API.

ScenarioWhat the fixture changesEvidence to inspect
Two workers, one allowanceBoth workers target the same documented scopeTheir combined behavior follows the configured shared policy, rather than each assuming the full allocation
Independent scopesOnly one scope receives a throttle signalUnaffected work is not paused by an unnecessarily global local gate; any real shared ceiling still applies
Nested constraintsOne operation hits its own constraint while global allowance remainsThe decision identifies the narrower constraint without treating the global remainder as permission
Slow responsesRequest duration rises while the start schedule stays fixedIn-flight work and queued work remain distinguishable and follow the declared policy
Mixed error reasonsFixtures return different documented reasons under similar HTTP statusesRecovery selects the intended branch rather than matching only the status code
Timing variantsDelay, date, absent and malformed fields appearParsing and fallback match the guide, with no unexplained immediate loop
Expired or cancelled jobEligibility ends while the worker is waitingThe job stops or is explicitly deferred according to the stated lifecycle
Multiple retry layersSDK attempts and worker redelivery are both enabledTotal attempts and ownership match the documented configuration
Worker restartA worker exits during a pause and resumes elsewhereRestart does not silently erase the intended coordination or expiry rule
Recovery waveMany waiting jobs become eligible togetherThe selected scheduling policy is observable, including its fairness and admission behavior

Write the expected outcome before running each fixture. "No errors" is not enough: a scheduler that freezes every queue can avoid errors while making the integration unusable. The independent-scope check is therefore as important as the shared-scope check. Both need the provider's actual boundaries as input.

For reproducible evidence, retain the fixture version, SDK settings, number of workers, synthetic scope identifiers, event timestamps and expected decisions. Separate attempted calls from completed jobs. Record the reason a job waited and the reason it resumed. A table of final success counts alone cannot show whether one customer was starved throughout the run.

The assertions should concern your implementation and documentation, not an invented provider guarantee. A fixture can demonstrate that your parser handles a date; it cannot prove that a remote service always sends one. It can show that your scheduler shares a configured allowance; it cannot establish the provider's hidden burst threshold.

If the result contradicts the guide, first determine whether the error is in the fixture, configuration, prose or implementation. Preserve that diagnosis alongside the correction. Otherwise, a passing rerun can hide the very assumption that the next example will repeat.

What a publishable capacity guide should let readers decide

A strong guide gives readers enough information to choose a coordination strategy without implying that they can predict every internal protection mechanism. We propose a compact review package: a scope statement, a worksheet, a realistic multi-worker example and the evidence behind its expected behavior.

Before publishing, ask a reviewer to answer these questions using only the guide:

  • Which callers compete for the same allowance, and which relationships remain unknown?
  • Which additional constraints can apply even when a visible counter has room?
  • What distinguishes a waiting job from a failed or expired job?
  • Which layer retries, with what configuration, and what can restart the whole task?
  • What happens to other customers when one scope is throttled?
  • What was checked locally, what was checked with a provider, and what was not tested?

Treat an unanswered question as a missing decision, not an invitation to invent a number. Some answers belong to the provider. Others belong to the integration owner. Label that ownership so a documentation update can be routed to the right person.

Keep a small change record beside the example: source access date, package version, relevant configuration and review date. Revisit it when the provider changes policy, an SDK changes behavior or the integration adds workers. This is a proposed maintenance practice, not evidence that a scheduled review alone prevents incidents.

For product teams, the useful outcome is a guide that explains both restraint and progress: when to wait, what may continue, and when to stop trying. That is the difference between documenting a response code and documenting an integration people can operate.

Limitations

This report compares selected public policies, not all operations, account tiers or SDK versions. Mutable provider documentation can change after November 22, 2026. No customer systems, provider capacity limits or production workloads were tested. We did not measure throughput, latency, fairness, failure rates or business outcomes. The numerical queue example is hypothetical. The worksheet and matrix are proposed methods that require adaptation and implementation-specific verification. Undisclosed limits remain unknown; local fixtures cannot establish them.

Sources

  1. RFC 6585: Additional HTTP Status Codes, section 4RFC Editor · Accessed 2026-11-22
  2. RFC 9110: HTTP Semantics, section 10.2.3RFC Editor · Accessed 2026-11-22
  3. Rate limits for the REST APIGitHub · Accessed 2026-11-22
  4. Web API rate limitsSlack · Accessed 2026-11-22
  5. Rate limitsStripe · Accessed 2026-11-22
  6. Timeouts, retries, and backoff with jitterAWS · Published 2019-12-05 · Accessed 2026-11-22
  7. Retry behaviorAWS · Accessed 2026-11-22