Rate Limits
Skirre applies rate limits per API key to ensure fair usage and protect service stability. Rate limit information is included in every API response via headers.
Default Limits
| Parameter | Type | Description |
|---|---|---|
| Requests per minute optional | limit | 1,000 requests per API key per 60-second window. |
| Window type optional | mechanism | Fixed 60-second sliding window. |
| Scope optional | mechanism | Rate limits are per API key, not per IP address or account. |
Rate Limit Headers
Every API response includes rate limit information in the headers:
text
X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 987
| Parameter | Type | Description |
|---|---|---|
| X-RateLimit-Limit optional | header | Maximum requests allowed per window for this key. |
| X-RateLimit-Remaining optional | header | Requests remaining in the current window. |
Rate Limit Errors
When the limit is exceeded, Skirre returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait:
text
HTTP/1.1 429 Too Many Requests Retry-After: 45 Content-Type: application/json
text
{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded. Retry after 45 seconds"
}
}Retry Strategy
The TypeScript SDK handles rate limits automatically with exponential backoff. If you're using raw HTTP, implement retries with these guidelines:
- Check the
Retry-Afterheader and wait at least that many seconds before retrying. - Use exponential backoff with jitter for multiple retries.
- Cap the maximum wait at 60 seconds.
- Limit total retries to 3–5 attempts.
SDK retry schedule
| Parameter | Type | Description |
|---|---|---|
| Attempt 1 optional | delay | 0.5s + random jitter |
| Attempt 2 optional | delay | 1s + random jitter |
| Attempt 3 optional | delay | 2s + random jitter |
| Attempt 4 optional | delay | 4s + random jitter (capped at 5s) |
Note
The SDK also retries on 5xx server errors using the same backoff schedule.
Configure the maximum number of retries with maxNetworkRetries when creating the
client.Best Practices
- Monitor headers. Check
X-RateLimit-Remainingin your responses to proactively slow down before hitting the limit. - Use separate keys. If you have multiple services or environments, use separate API keys so they don't share a rate limit budget.
- Batch document operations. Instead of indexing one document at a time, use batch upserts (up to 1,000 documents) to reduce the number of requests.
- Cache search results. For repeated queries (e.g. popular product categories), cache results on your application layer instead of hitting the search API every time.
- Use the SDK. The TypeScript SDK handles rate limit retries automatically, so you don't need to implement backoff logic yourself.