Summary
- When you exceed the allowed request rate, the API responds with HTTP 429 Too Many Requests.
- The response includes headers describing your short-term "burst" window and longer-term "quota" window, plus which policy was violated.
- Use those headers to determine how long to wait before retrying.
Limits
These are the current rate limits, these may be adjusted by so please refer to the headers of the response in case you exceed these limits.
| Name | Window | Limit |
|---|---|---|
| Burst | One minute | 9 000 |
| Quota | One hour | 270 000 |
When you encounter a 429 response you are expected to back off and let the limits cool off.
Any requests failing due to rate limiting will count toward the burst and quota limits.
HTTP 429 Response Details
What you'll receive when the rate-limit is exceeded
-
Status: 429 Too Many Requests
-
Body: {"detail": "Rate limit exceeded"}
-
Headers:
Name Description X-RateLimit-Burst maximum requests allowed in the short window X-RateLimit-Burst-Remaining remaining requests in the current short window X-RateLimit-Burst-Reset UNIX timestamp (seconds) when the short window resets X-RateLimit-Quota maximum requests allowed in the longer window X-RateLimit-Quota-Remaining remaining requests in the current long window X-RateLimit-Quota-Reset UNIX timestamp (seconds) when the long window resets X-RateLimit-Policy-Violated which policy triggered the block; either burst or quota
Example 429 response
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Burst: 10
X-RateLimit-Burst-Remaining: 0
X-RateLimit-Burst-Reset: 1747405140
X-RateLimit-Quota: 100
X-RateLimit-Quota-Remaining: 99
X-RateLimit-Quota-Reset: 1747407600
X-RateLimit-Policy-Violated: burst
{"detail":"Rate limit exceeded"}How to recover and retry safely
- Detect 429
- Treat 429 as a temporary condition; do not fail permanently.
- Choose how long to wait
- Identify the violated policy:
- If X-RateLimit-Policy-Violated is burst: wait until X-RateLimit-Burst-Reset.
- If it's quota: wait until X-RateLimit-Quota-Reset.
- The Reset headers are UNIX epoch seconds (UTC). Convert to your local time and compute wait = max(0, reset - now).