Rate Limits

Understand API rate limits and how to handle them gracefully.

Overview

Rate limits protect the API from abuse and ensure fair usage. Limits are applied per API key and vary by plan. When you exceed a limit, you'll receive a429 Too Many Requests response.

Rate Limit Headers

Every API response includes headers to help you track your usage:

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait (only on 429)

Limits by Plan

Plan	Requests/Min	Requests/Day	Burst
Free	60	500 / month	10
Starter	300	10,000 / month	50
Pro	1,000	50,000 / month	100
Enterprise	Custom	Unlimited	Custom

Handling Rate Limits

Best Practices

1.Check X-RateLimit-Remaining before making requests
2.Use exponential backoff on 429 responses
3.Respect the Retry-After header
4.Use batch endpoints for bulk operations
5.Consider upgrading if you consistently hit limits

429 Response Example

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705333200
Retry-After: 45

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please retry after 45 seconds.",
    "docs_url": "https://docs.katsau.com/rate-limits"
  }
}