Rate Limit Documentation — Complete Guide

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

Rate limit documentation tells developers how many requests they can make per time window, how to check their current usage via response headers, how to handle rate limit errors when they exceed limits, and recommended retry strategies like exponential backoff for production integrations.

What You'll Learn

How to document rate limits clearly by plan and endpoint, how to explain rate limit headers that track current usage, how to document the 429 error response format, how to recommend retry strategies with code examples, and how to handle burst and concurrent request limits.

Why It Matters

Undocumented rate limits cause mysterious 429 errors in production. Developers do not know why their requests are being rejected or when they can retry. Clear rate limit documentation helps developers design their integrations to stay within limits and handle errors gracefully.

Real-World Use

GitHub's Rate Limiting documentation is the gold standard. It documents limits per endpoint, provides usage headers on every response, and shows how to handle 429 errors with Retry-After headers. The DodaTech API follows the same pattern with plan-based limits and clear retry guidance.

Rate Limit Architecture

flowchart TD
  A[API Request] --> B{Within Limit?}
  B -->|Yes| C[Process Request]
  B -->|No| D[429 Response]
  C --> E[Include Usage 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. Use a table for quick reference.

## Rate Limits

Rate limits apply per API key and reset every hour.

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

If you exceed these limits, the API returns HTTP 429 with a
`Retry-After` header indicating when to retry.

Endpoint-Specific Limits

Document any endpoint-specific limits that differ from the general limits.

## Endpoint-Specific Limits

| Endpoint | Additional Limit | Notes |
|----------|-----------------|-------|
| POST /v2/files/compress | 10 requests per minute | Compression is resource-intensive |
| GET /v2/files | Same as general limit | No additional limits |
| POST /v2/files | 5 GB per hour total | Total upload size limit |

Rate Limit Response Headers

Every API response includes rate limit information in the headers.

## Rate Limit Headers

Every API response includes these headers showing your current usage:

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

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

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

## Rate Limit Error Response

Document the exact 429 error format.

```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"
  }
}

Retry Strategy

Show developers how to handle rate limits with proper retry logic.

import time
from dodatech import RateLimitError

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

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

    return None

# Usage
result = make_request_with_retry(client, "/v2/files")

Common Mistakes

1. No Rate Limit Documentation

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

2. No Usage Headers

Returning 429 without headers showing current usage or reset time leaves developers guessing when they can retry.

3. No Retry-After Header

The 429 response without a Retry-After header forces developers to guess how long to wait before retrying.

4. Undocumented Per-Endpoint Limits

Some endpoints have different limits. Not documenting these causes unexpected throttling on specific operations.

5. No Burst Limit Documentation

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

6. No Retry Strategy Guidance

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

7. Hidden Limit Changes

Changing rate limits without documentation breaks existing integrations. Always announce limit changes in the changelog.

Practice Questions

1. What rate limit headers should every API response include?

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

2. What is the Retry-After header?

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

3. Why document per-endpoint rate limits separately?

Resource-intensive endpoints like compression may have lower limits than simple list endpoints. Documenting per-endpoint limits prevents unexpected throttling.

4. What is burst rate limiting?

Burst limits restrict requests within a short time window (e.g., 10 per minute). They prevent rapid-fire requests even when the hourly limit has not been reached.

5. Challenge: Write rate limit documentation for an API with three pricing tiers, per-endpoint limits, usage response headers, error format, and retry strategy with code examples in two languages.

FAQ

Mini Project: Rate Limit Documentation

Write complete rate limit documentation for an API with three pricing tiers. Include a limits table, endpoint-specific limits, response header documentation, 429 error format, retry strategy with code examples in Python and JavaScript, and best practices for staying within limits.

What's Next

Rate limits protect your API resources. Now learn how to write effective code examples with Code Examples Best Practices. Then explore From cURL to SDK Examples.