Rate limits

Every API key has a ceiling on how many requests it may make per minute, set well above what normal use looks like: a polling job that checks who is on call every minute uses under 2% of the smallest allowance.

You do not have to guess where you stand. Every response tells you.

The allowance

Plan	Requests per minute, per key
Free	60
Pro	600

The ceiling is per key, not per workspace. Two integrations in the same workspace each get their own allowance, so a script stuck in a loop does not slow down the one running next to it. Give each integration its own key and this stays true.

The plan gates throughput, never access. Every /v1 endpoint your scopes allow works on Free; Pro simply lets you call it more often.

Every response says what is left

Three headers ride on every /v1 response authenticated with an API key, not just the refusals:

RateLimit-Limit: 60
RateLimit-Remaining: 58
RateLimit-Reset: 41

Header	Meaning
RateLimit-Limit	Your ceiling for this minute
RateLimit-Remaining	Requests left before you are refused
RateLimit-Reset	Seconds until the allowance refills

Because they are on successful responses too, you can slow down before being refused: read RateLimit-Remaining, and when it gets low, wait RateLimit-Reset seconds.

The window is a fixed minute, not a rolling one: RateLimit-Reset counts down to the next boundary, at which point the full allowance returns at once.

When you go over

You get 429 Too Many Requests, in the same problem document shape as every other refusal:

{
  "status": 429,
  "title": "Too many requests",
  "detail": "This key is over its limit of 60 requests per minute. Retry in 12 seconds, or spread the calls out: the RateLimit-Remaining header on every response says how much of the current window is left.",
  "code": "rate_limited"
}

The response carries Retry-After in seconds alongside the RateLimit-* headers. They agree with each other, so honour whichever your HTTP client already understands. Both are the real number of seconds and never zero.

Retry, do not hammer

Retrying immediately after a 429 just spends another request on another 429. Wait out Retry-After. If you retry on a schedule of your own, add jitter, because a fleet of clients that all wait exactly 60 seconds becomes a fleet of clients that all retry in the same instant.

The limit is approximate

Round Robin runs several API instances behind a load balancer, and each counts independently. In practice this means the effective ceiling is somewhat higher than the number above, and which instance answers a given request is not something you can predict.

So treat the allowance as a floor you can rely on rather than an exact quota. You will never be refused below it. You may occasionally get a little more.

A separate flood limit at the edge

Ahead of the API sits a network-level rule that blocks any single network address sending an extreme volume of traffic, thousands of requests a minute, far above any per-key allowance. It counts by address rather than by key, so it is not a per-customer quota and normal integrations never meet it.

It matters for one reason: if you ever see a 429 whose body has no RateLimit-* headers, that is the edge rule rather than your key’s allowance, and it means something is looping. Fix the loop rather than raising the retry interval.

Ask for a higher ceiling

If a legitimate integration genuinely needs more than 600 requests a minute, tell us what it does. Very often the answer is a cheaper request pattern rather than a bigger number: conditional reads with If-None-Match do not spend an extra request when nothing changed, and a wide page beats twenty narrow ones.

Next steps

• Conventions: paging, and the ETag reads that cut your request count
• Errors: the full code vocabulary a 429 belongs to
• Authenticating with an API key: where the per-key ceiling comes from