OpenAPI: Rate Limiting Response Headers

Q: OpenAPI: Rate Limiting Response Headers

## Documenting Rate Limiting in OpenAPI Rate limiting protects APIs from abuse. Documenting rate limit headers helps clients implement proper backoff and retry logic. ### Rate Limit Response Headers yaml components: headers: X-RateLimit-Limit: description: Maximum requests per window schema: type: integer example: 1000 X-RateLimit-Remaining: description: Remaining requests in current window schema: type: integer example: 998 X-

Document rate limiting headers (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After) in OpenAPI 3.0. Covers 429 responses and rate limit tier documentation.

Rate Limiting

Detailed Explanation

Documenting Rate Limiting in OpenAPI

Rate limiting protects APIs from abuse. Documenting rate limit headers helps clients implement proper backoff and retry logic.

Rate Limit Response Headers

components:
  headers:
    X-RateLimit-Limit:
      description: Maximum requests per window
      schema:
        type: integer
      example: 1000
    X-RateLimit-Remaining:
      description: Remaining requests in current window
      schema:
        type: integer
      example: 998
    X-RateLimit-Reset:
      description: Unix timestamp when the limit resets
      schema:
        type: integer
      example: 1698364800
    Retry-After:
      description: Seconds to wait before retrying (only on 429)
      schema:
        type: integer
      example: 60

Applying Headers to Responses

paths:
  /api/data:
    get:
      responses:
        '200':
          description: Success
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

Rate Limit Tiers

Document different rate limits for different authentication levels:

Tier	Limit	Window	Auth
Anonymous	60/hour	1 hour	None
Free	1,000/hour	1 hour	API Key
Pro	10,000/hour	1 hour	API Key
Enterprise	Custom	Custom	API Key

Client Implementation Guidance

In your API description, explain the recommended client behavior:

Check X-RateLimit-Remaining before each request
When receiving 429, read the Retry-After header
Implement exponential backoff for repeated 429s
Cache responses when possible to reduce request count

Use Case

Implementing rate limiting on a public API, developer platform, or any service that needs to protect against abuse while communicating limits transparently to API consumers.

Try It — API Documentation Generator

Open full tool →