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:

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.

📘

Note

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.

📘

Note

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:

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.