Rate limits

Requests are limited per API key, and every answer tells you where you stand, so a client can slow down before it is refused.

RateLimit-Limit: 100
RateLimit-Remaining: 97
RateLimit-Reset: 12

Rules

• RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds) come with every answer.
• Over the limit, the API answers 429 with type rate_limited, a Retry-After header and error.retry_after in seconds. Wait that long, then retry with the same idempotency key.
• The TypeScript SDK retries 429 and 5xx answers for you (2 retries by default, maxRetries to change it), honouring Retry-After.
• Each sender also has a sending rate (pacing). The send gate lets a sender send only so many messages a second; a send over it is also refused with 429 rate_limited, Retry-After and error.retry_after, and error.sender names the sender. Retry the same way, with the same idempotency key. The RateLimit-* headers describe only the per-key limit.
• New-contact budgets are separate. How many new conversations a sender may start is decided by the send gate (new_contact_limit, sender_throttled), not by these headers.
• Use webhooks or the live stream instead of polling GET /v0/events in a tight loop.