Rate limits - Synthesys Docs

The limits on each API key, what happens with missing or bad keys, the headers that report your usage, and how to handle a 429.

Limits apply to each API key, not to your IP address or to individual paths. Every route counts toward the same allowance, and two keys never share one.

API key tiers

Tier	Per minute	Per day
`standard`	100	10,000
`premium`	500	50,000
`enterprise`	2,000	500,000

Keys created in the dashboard use the standard tier, and the form doesn't let you choose another. Both windows are rolling, so capacity returns gradually as older requests leave the window.

A request counts once its key passes the check, even if the route then rejects it. A request refused for its size or for a bad key doesn't use any key's allowance.

Response headers

These headers appear on every request with a valid key, including a 429 for that key.

Header	Meaning
`X-RateLimit-Limit`	The key's per-minute allowance.
`X-RateLimit-Remaining`	Requests left in the current minute.
`X-RateLimit-Reset`	When the window has room again, as a Unix timestamp in seconds.
`Retry-After`	On a `429`, the seconds to wait.

What a 429 looks like

JSON

{
  "success": false,
  "error": "Too many requests. Please try again later.",
  "code": "RATE_LIMIT_EXCEEDED",
  "requestId": "6f1a2b3c-4d5e-4f60-8a7b-9c0d1e2f3a4b",
  "timestamp": "2026-10-31T09:30:00.000Z"
}

Over the per-minute limit, Retry-After gives the wait until the window has room. Over the per-day limit, Retry-After is 3600, because the oldest requests free up within an hour. The headers still describe the minute window, with X-RateLimit-Remaining at 0.

Missing or bad keys

A missing, malformed, wrong, revoked or expired key returns 401 and doesn't count against any key.

Each IP address can make 30 failed attempts in 15 minutes. After that, requests with a missing or bad key return 429 with the code RATE_LIMIT_EXCEEDED and a Retry-After header.

A valid key sent from the same address keeps working, because it is checked before the failure count. During a flood of bad keys from your address, a valid key can get a 429 with Retry-After: 2. Retry it after that wait.

How requests are counted

We run several server instances, and each one counts per-minute requests on its own. In practice:

X-RateLimit-Remaining can go up or down between responses, depending on which instance answers.
A key can sometimes exceed its per-minute figure before it gets a 429.
The daily count is shared between instances, but it updates about every 30 seconds, so it can overshoot slightly.

Treat the tier values as your budget, and don't rely on the extra room.

Handle a 429

Wait for Retry-After, then send the request again. Retrying POST /v1/calls with the same Idempotency-Key is safe. See Idempotency.

curl --retry 5 --retry-delay 60 https://backend.synthesys.app/api/v1/agents \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

Other limits on calls

POST /v1/calls has a separate limit of 100 calls queued or in progress for each account. Over that, it returns 429 with the code EXECUTION_CAPACITY_EXCEEDED and Retry-After: 60. See Capacity.

Use fewer requests

Use post-call webhooks instead of polling.
Request limit=100 when you need many records, so each request returns more.
Cache data that rarely changes, such as agents and phone numbers.
Read X-RateLimit-Remaining and slow down before it reaches zero.