Rate Limiting Guide

Synapse enforces per-tenant, per-endpoint-group rate limits to ensure platform stability and fair usage. This guide covers how limits are applied, how to handle 429 responses, and best practices for high-volume integrations.

How It Works

Rate limits use a sliding window algorithm with a 1-minute window. Each request is counted against your workspace's allowance for its endpoint group. When the window is full, subsequent requests receive a 429 Too Many Requests response until older entries expire.

All API keys within the same workspace share the same rate-limit window. Creating multiple keys does not increase your limit.

Endpoint Groups

Every API endpoint belongs to one of three rate-limit groups:

Group	Endpoints	Why separate
events	`POST /v1/events`, `POST /v1/events/batch`	Event ingestion is the primary integration point and needs higher throughput
send	`POST /v1/send`	Direct email sending is capped separately to prevent email flooding
general	All other `/v1/*` endpoints	CRUD operations, analytics, settings, reports

Limits by Plan

Requests per minute (RPM) per endpoint group:

Plan	General	Events	Send
Free	100	1,000	100
Starter	1,000	5,000	1,000
Growth	10,000	50,000	10,000
Enterprise	Unlimited	Unlimited	Unlimited

Note

If your plan is unknown or unrecognized, Free-tier limits apply as a safety fallback.

Rate Limit Headers

Every API response includes rate limit information in these headers:

Header	Description	Example
`X-RateLimit-Limit`	Maximum requests allowed in the current window	`1000`
`X-RateLimit-Remaining`	Requests remaining in the current window	`847`
`X-RateLimit-Reset`	Unix timestamp when the oldest entry in the window expires	`1746528900`

On a 429 response, an additional header is included:

Header	Description	Example
`Retry-After`	Seconds until the next request should be attempted	`42`

Example: Normal Response

HTTP/1.1 200 OK

X-RateLimit-Limit: 1000

X-RateLimit-Remaining: 847

X-RateLimit-Reset: 1746528900

Example: Rate Limited

HTTP/1.1 429 Too Many Requests

Retry-After: 42

X-RateLimit-Limit: 1000

X-RateLimit-Remaining: 0

X-RateLimit-Reset: 1746528900

Content-Type: application/json

json

{

"detail": "Rate limit exceeded",

"code": "rate_limit_exceeded"

}

Handling 429 Responses

Python -- Exponential Backoff

python

import time

import requests

def call_with_backoff(method, url, **kwargs):

max_retries = 5

for attempt in range(max_retries):

response = method(url, **kwargs)

if response.status_code != 429:

return response

# Use the server's Retry-After value

retry_after = int(response.headers.get("Retry-After", 2 ** attempt))

print(f"Rate limited. Retrying in {retry_after}s (attempt {attempt + 1})")

time.sleep(retry_after)

raise Exception("Rate limit exceeded after max retries")

JavaScript -- Exponential Backoff

javascript

async function callWithBackoff(url, options, maxRetries = 5) {

for (let attempt = 0; attempt < maxRetries; attempt++) {

const response = await fetch(url, options);

if (response.status !== 429) {

return response;

}

const retryAfter = parseInt(

response.headers.get("Retry-After") || String(2 ** attempt)

);

console.log(`Rate limited. Retrying in ${retryAfter}s (attempt ${attempt + 1})`);

await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));

}

throw new Error("Rate limit exceeded after max retries");

}

Tip

Always use the Retry-After header value instead of a fixed delay. The server calculates the optimal wait time based on your current sliding window state.

Proactive Throttling

Instead of reacting to 429 errors, you can proactively slow down by monitoring the X-RateLimit-Remaining header:

python

import time

def send_event(session, url, headers, event):

response = session.post(url, headers=headers, json=event)

remaining = int(response.headers.get("X-RateLimit-Remaining", 100))

if remaining < 50:

# Approaching limit -- slow down

time.sleep(0.1)

elif remaining < 10:

# Very close to limit -- pause longer

time.sleep(1.0)

return response

Event Ingestion Rate Limits

Event ingestion (POST /v1/events) has its own endpoint group with higher limits because it is the primary integration point between your application and Synapse.

For high-volume event producers:

Use batch ingestion (POST /v1/events/batch) -- send up to 50 events per request, each request counts as 1 against the rate limit
Use idempotency keys -- safe to retry without duplicate processing after a 429 error
Spread load across time -- if possible, avoid bursting thousands of events in a single second

Monthly Plan Limits

Separate from request rate limits, each plan has monthly caps on total usage:

Plan	Monthly Emails	Monthly Events	Contacts	API Keys
Free	1,000	10,000	1,000	2
Starter	10,000	100,000	10,000	10
Growth	100,000	1,000,000	100,000	50
Enterprise	Unlimited	Unlimited	Unlimited	Unlimited

When a monthly limit is reached, the relevant operation returns 403:

json

{

"detail": "Monthly email limit reached. Upgrade your plan or wait until the next billing period.",

"code": "plan_limit_reached"

}

Exempt Endpoints

The following paths are never rate-limited:

/health, /health/ready, /health/live -- health probes
/metrics -- application metrics
/docs, /openapi.json -- API documentation

Best Practices

Monitor X-RateLimit-Remaining -- proactively slow down before hitting the limit
Use the Retry-After header -- the server knows the optimal wait time
Batch events -- use POST /v1/events/batch for high-volume ingestion
Use idempotency keys -- safe retries after rate limit errors
Use the SDK -- the Python and JavaScript SDKs handle rate limit retries automatically
Contact support for Enterprise -- custom rate tiers are available

For the complete rate limit reference table, see Rate Limits Reference.