Rate limits

Limits are per workspace, per minute, not per key. Creating more keys does not buy more throughput.

Reading your budget#

Every response carries two headers:

RateLimit-Limit: 300
RateLimit-Remaining: 287

Read these rather than guessing. They are the only thing that tells you where you actually stand.

When you hit the limit#

{
    "error": {
        "type": "rate_limit_error",
        "code": "rate_limit_exceeded",
        "message": "Rate limit exceeded for the Launch plan. Check the RateLimit-* headers and retry after the reset; higher plans carry higher limits.",
        "request_id": "req_01k2p8w3q6z9y0abcdefgh7jkm"
    }
}

The response carries Retry-After in seconds. Wait that long, then retry. A fixed delay either wastes time or hammers us again; the header is exact.

if (response.status === 429) {
    const wait = Number(response.headers.get('Retry-After') ?? 1);
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
    // then retry
}

Limits that are not the plan limit#

The per-workspace budget above is the one you will normally meet. Narrower limiters sit alongside it, and each answers a 429 of its own, so a request can be refused while RateLimit-Remaining still looks healthy.

Unauthenticated requests: 30 per minute, per IP address. This covers the service index at /v1 and the OpenAPI document, which need no key. It is generous for a tool importing the spec and tight enough that the two endpoints without a key cannot be leaned on.

Redeeming and confirming invitations is limited separately. POST /v1/invitations/redeem, /v1/invitations/exchange and /v1/invitations/confirm each spend from the workspace budget and from a layered limiter on top of it: 10 a minute per invitation code, 20 a minute per identity, 60 a minute per source IP address across every project on the platform, plus a per-workspace ceiling. Redemption is the one endpoint where guessing pays, so it is bounded on several axes at once. A real signup flow meets at most one of them; an attacker has to beat all of them. A bulk integration running from a single egress IP address will meet the 60-a-minute per-IP axis first.

Resending a verification email is limited separately. POST /v1/contacts/{contact}/resend_verification re-issues a real email on every call, so it carries its own ceiling of 10 a minute per workspace on top of your plan's request budget. This is the limit a script re-confirming a list will meet, not the plan limit.

Importing is limited separately. POST /v1/imports spends from the workspace budget and from its own ceiling of 5 a minute and 30 an hour per workspace, because one call queues a whole import.

Broadcast tests and sends are limited separately. POST /v1/broadcasts/{broadcast}/test is limited to 12 a minute per workspace, and prepare and send to 10 a minute, each on top of your plan's request budget.

Repeatedly presenting a bad key is limited per IP address. After 30 failed authentication attempts we answer 429 with the code too_many_requests rather than another 401. This one is worth handling separately, because unlike every other 429 it carries no Retry-After and no RateLimit-* headers. Treat it as a signal that the credential is wrong, not that you are going too fast: retrying harder will not fix it. Wait a minute and fix the key.

Staying under it#

Do not poll. Use webhooks to be told when something happens instead of asking repeatedly whether it has.

Page in 100s. One request for 100 contacts costs one request from your budget, where four pages of 25 cost four.

Use /count for counts. It reads a maintained counter rather than paging.

Pace bulk work. A full sync that fires as fast as it can will spend its entire minute in the first two seconds and then stall. Spread it.

Next#

• Errors
• Pagination
• Webhooks: the alternative to polling