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

ParameterTypeDescription
Requests per minute optionallimit1,000 requests per API key per 60-second window.
Window type optionalmechanismFixed 60-second sliding window.
Scope optionalmechanismRate 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
ParameterTypeDescription
X-RateLimit-Limit optionalheaderMaximum requests allowed per window for this key.
X-RateLimit-Remaining optionalheaderRequests 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:

  1. Check the Retry-After header and wait at least that many seconds before retrying.
  2. Use exponential backoff with jitter for multiple retries.
  3. Cap the maximum wait at 60 seconds.
  4. Limit total retries to 3–5 attempts.

SDK retry schedule

ParameterTypeDescription
Attempt 1 optionaldelay0.5s + random jitter
Attempt 2 optionaldelay1s + random jitter
Attempt 3 optionaldelay2s + random jitter
Attempt 4 optionaldelay4s + 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-Remaining in 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.