Rate limits
Optimizely Graph enforces per-tenant rate limits across all API endpoints to ensure optimal performance and fair resource allocation. It applies the limits to each tenant individually and measures them over a 10-second window.
How rate limits work
Each API endpoint has a rate limit based on the resources it consumes. Endpoints that perform lightweight operations, such as read queries, have higher limits. Endpoints that modify data, such as content indexing or source management, have lower limits.
Optimizely Graph expresses each rate limit as the maximum number of requests allowed per 10-second window. For example, a limit of 1,500 per 10 seconds allows an average of 150 queries per second (QPS).
The same endpoint applies a separate limit and a separate counter to each HTTP method. For example, GET /api/content/v3/types, a read, has a higher limit than POST /api/content/v3/types, a write. The two do not share a budget.
Cache hit exemption
Requests served from the Optimizely Graph response cache do not count against your rate limit. This means you can increase your effective capacity by designing queries that maximize cache reuse.
Optimizely recommends the following practices:
- Use consistent query patterns to improve cache hit rates.
- Implement cache-control headers.
- Monitor your cache hit ratio to identify optimization opportunities.
By prioritizing cache hits, most applications operate well within their rate limits while achieving faster response times.
Response headers
Optimizely Graph includes the following headers in API responses:
Header | Description | Example |
|---|---|---|
X-RateLimit-Limit | Maximum requests allowed per window | 1500 |
X-RateLimit-Window | Window length in seconds | 10 |
Retry-After | Seconds to wait before retrying (only on 429 responses) | 10 |
X-RateLimit-Limit and X-RateLimit-Window appear on all responses, so your application knows what limit applies to each endpoint. Optimizely Graph includes Retry-After only on 429 responses.
X-RateLimit-Limit: 1500 with X-RateLimit-Window: 10 means your application can make 1,500 requests in any 10-second window, or 150 per second on average. Divide X-RateLimit-Limit by X-RateLimit-Window to get the per-second rate.
What happens when the limit is exceeded
When your application exceeds the rate limit for an endpoint, Optimizely Graph responds with HTTP 429, Too Many Requests. The response carries a structured error body:
{
"code": "RATE_LIMIT_EXCEEDED",
"status": 429,
"message": "Rate limit of 1500 requests per 10 seconds exceeded",
"details": {
"limit": 1500,
"window": 10,
"tenantId": "your-tenant-id"
}
}Optimizely Graph returns this response before the query reaches the GraphQL layer. Your application should handle it with retry logic, not treat it as a query error.
HTTP 429, which signals rate limiting, differs from HTTP 503. A 503 response indicates that the Cloudflare Worker platform ran out of CPU time while processing a heavy request. This is not rate limiting, and adjusting your QPS allocation does not resolve it. When you see 503 errors, simplify your queries or reduce concurrency.
Handle 429 responses
Design your application to handle 429 responses gracefully:
- Retry-After – Wait the indicated number of seconds before retrying.
- Exponential backoff – When retries continue to fail, increase the delay between attempts.
- Query patterns – Use the Optimizely Graph response cache and reduce request volume to stay within limits.
- X-RateLimit-Limit – Use the header value to understand the limit for each endpoint and size your request patterns accordingly.
Endpoint rate limits
Different endpoints have different limits based on the type of operation they perform. Read operations, such as GraphQL queries, have higher limits than write operations, such as content indexing or source updates. Reads consume fewer back-end resources.
Most application traffic uses GraphQL queries on /content/v2. That endpoint allows 1,500 requests per 10-second window, or 150 QPS, by default. Tenants with elevated allocations get 3,000 requests per 10-second window, or 300 QPS.
The following table summarizes the rate limits by operation category:
Operation | Rate limit (per 10-second window) |
|---|---|
Configuration writes (content types, sources, OIDC) | 10 requests |
Account operations (create, delete, swap) | 50 requests |
Content indexing, synonyms (write), stopwords (write) | 500 requests |
Webhooks, pinned results, best bets, cache config, request logs | 1,000 requests |
GraphQL queries, content type reads, source reads, synonym reads | 1,500 requests (default) |
GraphQL queries, content reads (elevated allocation) | 3,000 requests |
Optimizely Graph applies your account's QPS allocation per endpoint, but the allocation cannot exceed the endpoint's own maximum. The following constraints apply:
- The X-RateLimit-Limit header varies across endpoints. A GraphQL query response shows X-RateLimit-Limit: 1500 while a content type update shows X-RateLimit-Limit: 10. This is expected, because each endpoint advertises its own limit.
- Your QPS allocation can lower an endpoint's limit, but never raise it. When your account has 150 QPS but a write endpoint caps at 50 QPS, you get 50 QPS. The endpoint's maximum reflects what the underlying infrastructure can sustain.
- An allocation between two limit levels rounds up to the next level. For example, an allocation of 200 QPS rounds up to 300 QPS on read endpoints. The X-RateLimit-Limit header shows the enforced limit, so use it as the source of truth.
Check the X-RateLimit-Limit header on each endpoint's response to see the effective limit for that operation.
Request higher rate limits
If your application requires a higher query rate, custom rate limits are available. Contact your Optimizely account team to discuss your specific needs.
How Optimizely sets rate limits
Optimizely sets rate limits based on analysis of customer usage across the platform. The goal is to maintain service quality while keeping limits above normal production usage. When you have questions about your usage patterns or need help optimizing for rate limits, contact Optimizely Support.