An API that returns 429 without documenting its limits forces consumers to discover the ceiling experimentally — in production, under real traffic, during a critical path. Rate limit headers (X-RateLimit-Remaining, Retry-After) are useless if consumers don't know to read them. Undocumented quotas also block capacity planning: a company considering integration cannot evaluate whether a free tier meets their use case without knowing the specific numbers. iso-25010:2011 analysability requires that all operational constraints on a system be documented, not discovered.
Medium because the failure creates operational surprises rather than blocking initial adoption, but undocumented rate limits lead directly to production incidents when integrators hit limits they didn't know existed.
Add a Rate Limits section that specifies exact numbers, the window, and the response headers:
## Rate Limits
| Plan | Requests | Window |
|------|----------|--------|
| Free | 100 | per minute |
| Pro | 1,000 | per minute |
Every response includes rate limit headers:
- `X-RateLimit-Limit`: Maximum requests in the current window
- `X-RateLimit-Remaining`: Requests left before you are throttled
- `Retry-After`: Seconds to wait on a 429 response
Do not write 'rate limits apply' without the actual numbers. Vague rate limit documentation is treated the same as missing documentation.
ID: developer-documentation.api-reference.rate-limit-docs
Severity: medium
What to look for: If the API or service has rate limits, check whether they are documented. Look for information about request limits (per minute, per hour, per day), response headers that communicate rate limit status (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After), and different limits for different tiers or endpoints. Count all instances found and enumerate each.
Pass criteria: Rate limits are documented with specific numbers (e.g., "100 requests per minute"), the response headers that communicate rate limit status, and what happens when limits are exceeded (429 response, retry behavior). At least 1 implementation must be confirmed.
Fail criteria: The API has rate limits (returns 429 responses) but they are not documented, or docs mention rate limits exist without specifying the actual limits.
Skip (N/A) when: The project has no rate limits (offline library, local CLI tool) or is not a hosted API/service.
Detail on fail: Example: "API returns 429 Too Many Requests but documentation does not mention any rate limits" or "Docs say 'rate limits apply' but don't specify the actual limits or how to check remaining quota"
Remediation: Add rate limit documentation:
## Rate Limits
| Plan | Limit | Window |
|------|-------|--------|
| Free | 100 requests | per minute |
| Pro | 1,000 requests | per minute |
Rate limit headers are included in every response:
- `X-RateLimit-Limit`: Maximum requests per window
- `X-RateLimit-Remaining`: Requests remaining in current window
- `Retry-After`: Seconds to wait when rate limited (on 429 responses)