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.
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.
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 context | Documented boundary or signal | Documentation lesson |
|---|---|---|
| GitHub REST API | User-authenticated calls can share a personal allowance. Installation authentication has different rules. | Explain authentication identity before presenting a quota number. GitHub |
| Slack Web API | Web API limits follow the method, workspace and app. | Show the scope of the pause, not just the waiting period. Slack |
| Stripe API | The 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 field | What to write down | Example of evidence to attach |
|---|---|---|
| Consumer identity | Which accounts, apps, credentials, workers or resources share the allowance | Provider scope statement and an annotated two-worker example |
| Counting unit | Requests, weighted operations, bytes, active operations or another stated unit | The exact operation or quota reference |
| Time basis | Window, reset signal or refill behavior, if documented | A response example with units and interpretation |
| Concurrent work | Applicable in-flight boundary and what ends an occupied slot | Operation lifecycle and concurrency policy |
| Overlapping constraints | Global, operation-specific and resource-specific rules that also apply | A diagram or list showing the combination |
| Local queue policy | Priority, expiry and treatment of delayed work | An application-owned decision, labeled separately |
| Environment | Sandbox, production, account tier and SDK configuration | The 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:
- Identify the provider error category and the affected scope.
- Interpret the documented timing signal and retain enough evidence to explain the decision.
- Check whether the operation remains eligible to run, including cancellation and expiry.
- Schedule eligible work according to the provider policy and the application's coordination rules.
- 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 integration | Question the guide should answer | Evidence for the example |
|---|---|---|
| Application job | Can the entire task restart, and does it keep completed progress? | Job lifecycle and restart rule |
| Queue worker | Does redelivery replay the same operation or resume a checkpoint? | Worker configuration and failure example |
| HTTP client or SDK | Which failures trigger another transport attempt? | Package version, retry mode and explicit configuration |
| Shared scheduler | Which consumers wait after one receives a throttle signal? | Scope mapping and recorded decisions |
| User action | Can 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.
| Scenario | What the fixture changes | Evidence to inspect |
|---|---|---|
| Two workers, one allowance | Both workers target the same documented scope | Their combined behavior follows the configured shared policy, rather than each assuming the full allocation |
| Independent scopes | Only one scope receives a throttle signal | Unaffected work is not paused by an unnecessarily global local gate; any real shared ceiling still applies |
| Nested constraints | One operation hits its own constraint while global allowance remains | The decision identifies the narrower constraint without treating the global remainder as permission |
| Slow responses | Request duration rises while the start schedule stays fixed | In-flight work and queued work remain distinguishable and follow the declared policy |
| Mixed error reasons | Fixtures return different documented reasons under similar HTTP statuses | Recovery selects the intended branch rather than matching only the status code |
| Timing variants | Delay, date, absent and malformed fields appear | Parsing and fallback match the guide, with no unexplained immediate loop |
| Expired or cancelled job | Eligibility ends while the worker is waiting | The job stops or is explicitly deferred according to the stated lifecycle |
| Multiple retry layers | SDK attempts and worker redelivery are both enabled | Total attempts and ownership match the documented configuration |
| Worker restart | A worker exits during a pause and resumes elsewhere | Restart does not silently erase the intended coordination or expiry rule |
| Recovery wave | Many waiting jobs become eligible together | The 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
- RFC 6585: Additional HTTP Status Codes, section 4RFC Editor · Accessed 2026-11-22
- RFC 9110: HTTP Semantics, section 10.2.3RFC Editor · Accessed 2026-11-22
- Rate limits for the REST APIGitHub · Accessed 2026-11-22
- Web API rate limitsSlack · Accessed 2026-11-22
- Rate limitsStripe · Accessed 2026-11-22
- Timeouts, retries, and backoff with jitterAWS · Published 2019-12-05 · Accessed 2026-11-22
- Retry behaviorAWS · Accessed 2026-11-22