Rate limits and quotas are documented
Why it matters
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.
Severity rationale
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.
Remediation
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.
DetectionPro
The detection method for this pattern is part of AuditBuffet Pro.
The full method (what to look for, pass and fail conditions, and how results get reported) ships inside the Developer Documentation Audit. The pattern definition, severity rationale, and remediation remain openly licensed under CC-BY-4.0.
External references
- iso-25010:2011 · maintainability.analysability
Taxons
History
- 2026-04-18·v1.0.0·Initial import from developer-documentation·automated