Course contentsShow
← AI Engineering
Lesson 992 of 1,88624. Building AI APIsFree lesson

Rate Limit Headers and Client Communication

Returning standard rate limit headers (X-RateLimit-*) and providing clear error responses (429 status).

Rate Limit Headers and Client Communication

What you'll learn: How to tell API clients when they're hitting rate limits using standard HTTP headers and clear error responses.

Why Communication Matters

You've implemented rate limiting (concepts 988-991), but if clients don't know why their requests are failing or when they can retry, they'll keep hammering your API or abandon it entirely. Good rate limit communication turns frustration into predictable, manageable behavior.

Think of it like a busy restaurant: instead of just turning people away, you give them a ticket number and an estimated wait time.

Standard Rate Limit Headers

The widely-adopted pattern uses three HTTP headers in every response (success or rate-limited):

  • X-RateLimit-Limit: Maximum requests allowed in the window (e.g., 100)
  • X-RateLimit-Remaining: How many requests the client has left (e.g., 47)
  • X-RateLimit-Reset: Unix timestamp when the limit resets (e.g., 1704067200)

These headers let clients proactively slow down before hitting the limit.

The 429 Too Many Requests Response

When a client exceeds their limit, return:

  • HTTP status code 429 (standard for rate limiting)
  • The same three headers above (with Remaining: 0)
  • Optional: Retry-After header with seconds until reset
  • A JSON body explaining the issue clearly
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704067200
Retry-After: 3600

The error body might say: {"error": "Rate limit exceeded", "retry_after_seconds": 3600}.

Client-Friendly Design

Clear communication means clients can implement exponential backoff, display countdowns to users, or queue requests intelligently—all without guessing.

Key Takeaway: Return X-RateLimit-* headers on every response and use 429 status with Retry-After for exceeded limits, enabling clients to self-regulate gracefully.