Rate Limits
Understand rate limiting and how to handle 429 responses.
Default limits
The Wahlu API allows 100 requests per minute per API key. This limit applies across all endpoints.
Rate limit headers
Every API response includes headers that tell you your current rate limit status:
| Parameter | Type | Description |
|---|---|---|
X-RateLimit-Limit | integer | The maximum number of requests allowed per minute. |
X-RateLimit-Remaining | integer | The number of requests remaining in the current window. |
X-RateLimit-Reset | integer | Unix timestamp (seconds) when the rate limit window resets. |
Example response headers
HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1739352060Exceeding the limit
When you exceed the rate limit, the API returns a 429 Too Many Requests response. The response body includes a RATE_LIMITED error code and the Retry-After header tells you how many seconds to wait.
429 response
HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1739352060
{
"success": false,
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Retry after 23 seconds."
}
}Best practices
- Check the headers — Monitor
X-RateLimit-Remainingand slow down before hitting zero. - Implement exponential back-off — When you receive a 429, wait for the
Retry-Afterduration, then gradually increase delays on repeated failures. - Batch where possible — Use list endpoints with pagination instead of fetching items one by one.
- Cache responses — Store responses locally when the data doesn't change frequently.