API Reliability
API Rate Limit Headers Guide
Interpret 429 responses, Retry-After and common rate-limit headers while keeping client throttling observable and predictable. This reference is written for developers who need practical validation behavior, reviewable rules and safe examples rather than copied snippets with no explanation.
Recommended workflow
| Step | Why it matters |
|---|---|
| Read the status and body | A 429 body often identifies the quota scope or operation that was limited. |
| Honor server timing | Retry-After can be seconds or an HTTP date, so parse both forms. |
| Throttle before exhaustion | Remaining and reset hints can smooth traffic before requests fail. |
| Measure by caller | Separate user, token, tenant and global quota metrics. |
Starter snippet
curl -i https://api.example.test/resource
# Inspect status, Retry-After, remaining quota and reset time.Review checks
- Treat undocumented X-RateLimit headers as provider-specific.
- Use a monotonic wait timer after parsing reset time.
- Avoid logging full authorization tokens.
- Expose final rate-limit failure to callers clearly.
Common mistakes
- Immediately retrying every 429 response.
- Assuming reset timestamps use local time.
- Sharing one client quota bucket across unrelated tenants.
Validation should help users correct input while protecting systems from bad data. Keep syntax checks, product policy, security review and deliverability checks separate.
Related Formalint references
Continue with Api Rate Limit Debugging, Curl Headers Debugging Guide, API Retry and Exponential Backoff.