A quota is only part of the contract: the counted event, identity scope, window, reset rule, and client guidance determine what a useful scenario can check. Expect a particular status or Retry-After header only when the supplied contract defines it.
Why this Skill is needed
API Rate Limit Testing turns documented quotas into traceable scenario candidates. A review can expose gaps in identity scope, counted events, window boundaries, burst allowance, response guidance, and recovery before anyone runs a test.
What the Skill does
Use this Skill to design a bounded review of quota identity, window boundaries, burst behavior, response metadata, retry timing, and recovery. It organizes candidates and evidence requests; it does not execute them.
Awesome QA Skills organizes Skills by language and testing stage. The series overview explains the shared installation model; this guide stays with API Rate Limit Testing.
A useful first pass records the quota limit N, the event being counted, identity key, window algorithm, time source, burst allowance, reset behavior, and response contract. Where those rules are known, candidates can compare N-1, N, and N+1, a permitted in-quota control, a window boundary, a burst, a separate identity, and recovery. Missing counting or clock rules stay open questions; they are not filled in from convention.
Use it when the team needs a repeatable review of quota identity, window boundary, burst behavior, response metadata, retry timing, and recovery—especially when sources disagree or a handoff must show what remains unverified.
What it does not do
The API Rate Limit Testing Skill can organize quota-policy material, evidence, and next actions. It does not replace:
- Confirmation of rules, scope, and risk by the accountable domain owner.
- A real environment, account, dataset, log, or run record; static analysis does not become runtime evidence by itself.
- Authorization for release, compliance, production actions, or residual-risk acceptance.
- A Human decision when supplied sources conflict.
What it checks
The value of this Skill is not another keyword list. It connects each focus area to an observable input, a judgment, and a way to close the loop. Start with a small matrix based on the source Skill’s output contract:
| Evidence area | Capture from the source | Candidate checks |
|---|---|---|
| Quota ledger | Limit N, which successful/rejected events count, user/tenant/route key, window and time source | Compare N-1, N, and N+1 only when the counting rule is explicit; retain an allowed in-quota control |
| Burst and reset | Documented burst allowance, algorithm, reset rule, and boundary semantics | Check the stated burst and before/at/after-window cases; do not infer a fixed, sliding, or token-bucket algorithm |
| Response and retry | Contracted status, remaining-quota fields, retry hint, client budget, and side effects | Check only fields the contract promises; preserve hint-aware retry, total retry budget, and counted-failure behavior as candidates |
| Isolation and recovery | Identity dimensions and expected effect on other subjects | Compare one identity dimension at a time; check unaffected subjects and early/late recovery |
If a row has only a conventional expectation and no source or validation method, keep it open instead of turning it into a pass.
Audit inputs before you start
Before analyzing the quota contract, classify the input into six evidence states. A gap is not automatically a failure, but it must not disappear inside the conclusion.
| State | Meaning | How this Skill should handle it |
|---|---|---|
| known | Directly supported by the supplied material | Keep the source, version, and time with the judgment |
| missing | Needed for this pass but not supplied | Name the smallest evidence action and limit the conclusion |
| conflicting | Sources disagree | Show both sources and route the conflict to an owner |
| stale | Present but outside the relevant version or time window | Mark freshness; old evidence is not current proof |
| out_of_scope | Related but excluded from this pass | Keep the boundary explicit |
| assumptions | Temporarily adopted to continue analysis | State how and when the assumption will be checked |
Keep the input version, scope, environment, evidence locations, and accountable owner together. Without a run record, deliver analysis, design, or a validation plan—not an execution pass.
From problem to structured Finding
Connect the source, scope, evidence state, analysis, owner, action, close condition, and validation before writing the conclusion. The case below keeps this Skill’s identifier and domain context.
Keep the decision layers separate
For Limit decision, do not compress four different kinds of language into “recommended to pass”:
| Layer | How to write it | Application here |
|---|---|---|
| Fact | What the supplied material directly shows | Cite the source, version, input, or run record for the focus |
| Evidence-backed Inference | What several facts support together | Show the inference chain and retain uncertainty |
| Recommendation | The smallest next action | Name the evidence, review, execution, or regression path |
| Human Decision | What an accountable person must decide | Leave scope, risk acceptance, resources, and release meaning to the owner |
A complete case
This case follows Input, Analysis, Finding, Decision, and Validation. When material is incomplete, keep missing, conflicting, or assumptions visible instead of turning them into a pass.
Input
| Material | What to provide | What to do when it is missing |
|---|---|---|
| Limit contract | Quota, counted event, window algorithm, burst, identity key, reset, and response fields | Mark undocumented rules missing; do not supply conventional defaults |
| Scenario boundary | Subject, endpoint, approved environment, and allowed traffic | Keep a proposed scenario separate from an executed load or test |
| Recovery evidence | Contracted retry hint, remaining count, time source, and recovery condition | Keep absent clock or retry rules unassessed |
Use a request like this:
Use the api-rate-limit-testing Skill.
Task: design evidence-bounded scenarios for a report-export API with per-user and per-tenant quotas and browser clients that may retry after a limit response
Inputs: [requirements, versions, links, logs, reports, or data paths]
Scope: [included and excluded objects]
Unknowns: [missing environment, accounts, data, or permissions]
Expected output: [risk-ordered findings, evidence status, and next actions]
Audit the inputs first. Separate facts, assumptions, and open questions. Do not claim execution without a run record.Analysis
Start with a bounded design pass for the report-export API. If the supplied policy defines a per-user limit N, its counted event, and window, outline N-1, N, and N+1 candidates plus an allowed control. Add a second user or tenant only to distinguish the documented identity scopes. Include burst and window-boundary candidates when the policy defines them. Treat 429, remaining-quota fields, and Retry-After as expected evidence only if the contract promises them. Mark every candidate NOT_RUN until a real run record exists; do not exhaust a shared quota as part of this design review.
The handoff should preserve the input version, time window, evidence index, owner, and next validation action. The Skill can organize uncertainty; it cannot manufacture the missing artifact.
Finding
Example finding: turn one problem into a handoff
The field example below shows the recording pattern; it is not an execution result.
Use an ARL-## record when a quota rule or scenario needs a traceable decision. This example keeps absent policy details visible; it does not claim a test ran.
| ARL-01 field | Report-export per-user quota |
|---|---|
| Subject and preconditions | Report-export per-user quota; capture the actual limit, counted event, window, and time source before deriving boundary cases |
| Behavior of concern | Whether N-1, N, and N+1 requests follow the documented quota rule; status and headers remain contract-dependent |
| Source and evidence state | Quota policy/version not supplied: missing; candidate is NOT_RUN |
| Impact and priority | Describe affected users or tenants from evidence; leave priority for the accountable owner if impact is unknown |
| Owner and close condition | Policy/API owner confirms scope and counting semantics; close the design gap when the source and expected outcomes are reviewable |
| Validation | A later approved run records identity, request sequence, timestamps, raw responses, and post-window behavior; execution status stays NOT_RUN until then |
The point is to let the next person walk from the finding back to the source and run an action that can change the decision.
Decision
The accountable owner confirms the decision question and risk trade-off; the Skill does not make that choice.
Validation
Before closing the finding, run the stated validation and retain the raw artifact. Without an execution record, the status remains unverified.
How a Finding enters the next stage
Handoff output
| Output | Required detail | Example status |
|---|---|---|
| Quota ledger | N, counted event, subject key, window/time source, and source version | missing if policy is absent |
| Scenario candidate | Preconditions, boundary or burst behavior, allowed control, and expected contract evidence | NOT_RUN until a run artifact exists |
| Isolation/recovery | Other subject affected, retry budget, and recovery condition | unassessed where rules or observations are absent |
Do not write “passed” without a run record. In the design, vary one identity dimension at a time, use a documented time source if one exists, and specify the observation needed during the limited period and after recovery. If those rules are absent, record the gap instead of inventing a delay or status.
Next-stage route
At minimum, hand off the source, evidence state, owner, close condition, and validation action; the next-stage conclusion remains bounded by the evidence state.
How to prepare better input
If the first request contains only a one-line goal, keep the output limited. Add the source version, affected objects, environment, known defects, and decision owner to move from a plausible checklist to a useful review.
A richer input changes the answer here because quota identity, window boundary, burst behavior, response metadata, retry timing, and recovery must be tied to evidence rather than inferred from a familiar pattern.
Working with other Skills
- API Negative Testing:covers limit and rejection inputs.
- Retry Testing:checks backoff and retry boundaries.
- API Error Contract Testing:validates actionable rate-limit errors.
Common traps
- Testing only one identity.
- Ignoring clock skew and retry headers.
- Calling a 429 response fair without checking unaffected users and tenants.
Install and invoke
Install the individual Skill. The series overview carries the longer installation explanation.
npx skills add https://github.com/naodeng/awesome-qa-skills/tree/main/skills/en/testing-types/api-rate-limit-testing -gAfter installation, invoke it with the api-rate-limit-testing Skill and attach the real project material.
FAQ
Should rate-limit tests use a real quota?
This Skill designs scenarios and does not consume quota. For a later authorized run, use an isolated quota or controllable policy; do not exhaust shared production capacity.
What if Retry-After is missing?
Record the contract gap. Do not assume Retry-After, another header, a status code, or a client delay unless the applicable contract defines it.
The example above is a design and review pattern, not an execution result. Keep static analysis, runtime evidence, human approval, and release acceptance separate.
References
Source Skill and execution contract
The complete execution contract lives in the API Rate Limit Testing prompt. Read it before invoking the Skill; the prompt defines the detailed workflow and output contract. The source directory contains the entry point and supporting assets where they exist.
The entry point centers quota identity, window boundary, burst behavior, response metadata, retry timing, and recovery. Keep its decision boundary visible and do not turn a static design into an execution claim.
Reference links
-
API Rate Limit Testing prompt:https://github.com/naodeng/awesome-qa-skills/tree/main/skills/en/testing-types/api-rate-limit-testing/prompts/api-rate-limit-testing.md
-
Awesome QA Skills: API Rate Limit Testing source:https://github.com/naodeng/awesome-qa-skills/tree/main/skills/en/testing-types/api-rate-limit-testing
-
Awesome QA Skills GitHub:https://github.com/naodeng/awesome-qa-skills
-
API Rate Limit Testing details:https://inaodeng.com/en/qaskills/api-rate-limit-testing/