Rate Limiting Documentation — Complete Guide

In this tutorial, you will learn about Rate Limiting Documentation. We cover key concepts, practical examples, and best practices to help you master this topic.

Rate limiting documentation tells developers how many requests they can make per time window, what happens when they exceed the limit, and how to handle rate limit errors with retry strategies like exponential backoff and retry-after header support.

What You'll Learn

How to document rate limits clearly, how to show developers their current usage, how to explain rate limit error responses, how to recommend retry strategies like exponential backoff, and how to handle burst limits and concurrent request limits.

Why It Matters

Every API has limits. Undocumented rate limits cause mysterious 429 errors that developers cannot debug. Clear rate limiting documentation helps developers design their integrations to stay within limits and handle limit errors gracefully when they occur.

Real-World Use

GitHub's API rate limiting documentation shows the limit per authenticated user, the headers to check current usage, and how to handle the 429 response. DodaTech's APIs follow the same pattern: documented limits, usage headers, and clear retry guidance.

Rate Limit Architecture

flowchart TD
  A[Developer Request] --> B{Within Limit?}
  B -->|Yes| C[Process Request]
  B -->|No| D[429 Rate Limited]
  C --> E[Return Response + Headers]
  D --> F[Retry-After Header]
  F --> G[Developer Retries]
  G --> B
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Documenting Rate Limits

Be specific about limits per plan, time window, and endpoint.

## Rate Limits

Rate limits vary by subscription plan:

| Plan | Requests per Hour | Burst Limit | Concurrent Requests |
|------|------------------|-------------|-------------------|
| Free | 100 | 10 | 2 |
| Pro | 1,000 | 100 | 10 |
| Enterprise | 10,000 | 500 | 50 |

Rate limits reset every hour at the start of the next hour window.
Burst limits restrict requests within a 10-second window.

Rate Limit Headers

Document the response headers that let developers track their usage.

## Rate Limit Headers

Every API response includes rate limit information in the response headers:

| Header | Description | Example |
|--------|-------------|---------|
| X-RateLimit-Limit | Maximum requests per hour | 1000 |
| X-RateLimit-Remaining | Requests remaining in current window | 842 |
| X-RateLimit-Reset | Unix timestamp when limit resets | 1759123456 |
| Retry-After | Seconds to wait (only on 429) | 37 |

```bash
curl -I -H "Authorization: Bearer YOUR_KEY" \
  https://api.dodatech.com/v2/files

# Response headers:
# HTTP/2 200
# X-RateLimit-Limit: 1000
# X-RateLimit-Remaining: 842
# X-RateLimit-Reset: 1759123456

## Rate Limit Error Response

Document the exact error format for 429 responses.

```json
// HTTP 429 Too Many Requests
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Retry after 37 seconds.",
    "retry_after": 37,
    "limit": 1000,
    "remaining": 0,
    "reset_at": "2026-07-01T12:00:00Z",
    "docs_url": "https://docs.dodatech.com/api/rate-limits"
  }
}

Retry Strategies

Show developers how to handle rate limits correctly.

import time
from dodatech import Client, RateLimitError

def rate_limited_request(client, endpoint, **kwargs):
    max_retries = 5
    base_delay = 1

    for attempt in range(max_retries):
        try:
            return client.request(endpoint, **kwargs)
        except RateLimitError as e:
            if attempt == max_retries - 1:
                raise

            # Use Retry-After header if available
            delay = e.retry_after or (base_delay * (2 ** attempt))
            print(f"Rate limited. Waiting {delay}s (attempt {attempt + 1})")
            time.sleep(delay)

    return None

Best Practices for Developers

## Rate Limit Best Practices

1. **Check rate limit headers** before processing. If remaining is low,
   queue requests for the next window.

2. **Implement exponential backoff** with jitter to avoid thundering herd
   problems when the rate limit resets.

3. **Use the Retry-After header** when available. It is more accurate than
   calculated backoff.

4. **Batch requests** where possible. Compress 10 files in one request
   instead of 10 individual requests.

5. **Upgrade your plan** if you consistently approach the limit.

Rate Limiting Per Endpoint

Some endpoints may have different limits. Document endpoint-specific limits.

## Endpoint-Specific Limits

| Endpoint | Additional Limit | Notes |
|----------|-----------------|-------|
| POST /v2/compress | 10 requests per minute | Compression is resource-intensive |
| GET /v2/jobs/{id} | No additional limit | Same as general rate limit |
| POST /v2/files | File upload: 5 GB per hour | Total upload size across all requests |

Common Mistakes

1. No Rate Limit Documentation

Not documenting rate limits anywhere causes developers to discover them through unexpected 429 errors in production.

2. Undocumented Per-Endpoint Limits

Documenting general limits but not endpoint-specific limits causes unexpected throttling on specific operations.

3. No Usage Headers

Returning 429 without usage headers leaves developers guessing when the limit will reset and how close they are to the limit.

4. Generic Error Response

Returning 429 Too Many Requests with no retry_after field forces developers to guess how long to wait.

5. Hidden Limit Changes

Changing rate limits without notice breaks existing integrations. Document limit changes in the changelog with advance notice.

6. No Burst Documentation

Documenting hourly limits but not short-term burst limits causes developers to exceed burst limits while staying under hourly limits.

7. No Retry Strategy Recommendation

Documenting the limit but not how to handle it forces developers to design their own retry logic from scratch.

Practice Questions

1. What are the three rate limit headers every API should return?

X-RateLimit-Limit (maximum requests per hour), X-RateLimit-Remaining (requests remaining), and X-RateLimit-Reset (timestamp when the limit resets).

2. Why use exponential backoff for rate limit retries?

Exponential backoff prevents thundering herd problems where all clients retry at the same time. Starting with a short delay and increasing it reduces server load and improves success rates.

3. What is the Retry-After header?

The Retry-After header tells the client exactly how many seconds to wait before retrying. It is more accurate than calculated backoff because the server knows exactly when the limit resets.

4. Why document per-endpoint rate limits?

Some endpoints are more resource-intensive than others. Compression endpoints might have lower limits than list endpoints. Documenting per-endpoint limits prevents unexpected throttling.

5. Challenge: Write rate limiting documentation for an API with three pricing tiers, endpoint-specific limits, usage headers, and recommended retry strategies with code examples.

FAQ

Mini Project: Write Rate Limiting Docs

Write complete rate limiting documentation for an API with three pricing tiers. Include a limits table, response header documentation, error response format, retry strategy code examples, per-endpoint limits, and best practices for developers.

What's Next

Rate limits protect your API. Now learn to document each operation with Endpoint Documentation. Then explore Parameter Documentation for documenting request parameters clearly.