Request limits
Limits count requests per API key, in fixed one-minute windows.
Responses include
RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers; RateLimit-Reset is the number of seconds until the window resets, on every response including a 429. Over a limit, you get 429 RATE_LIMIT_EXCEEDED with a Retry-After header:
retry_after and reset_at on the error match the Retry-After header. details[0].limit_type tells you which request limit you hit: public_api_read, public_api_write or public_api_media. The same error code with scope: "phone_number" and a limit_type of new_contact_daily, recipient_loop or phone_number_sendability is a sending limit on the number, not a request limit. See Handle limit errors on sends.
Capability checks
POST /v1/capability/evaluate_service runs a fresh check on the phone number you name. Each number can run 30 fresh checks per clock hour and 100 per UTC day. An answer Blujay already has, from any check or send in the last 5 minutes (30 seconds for a check that didn’t confirm anything), comes back with source: "cached", and cached answers are free and unlimited.
Over the quota, the check returns 429 RATE_LIMIT_EXCEEDED with Retry-After. Sending with Auto (no preferred_service) never needs a check first.
Backing off
- On
429or a retryable503, wait forRetry-Afterseconds. - Retry with the same
Idempotency-Key. - If it fails again, back off exponentially with jitter, up to a few minutes.
- Don’t retry non-retryable errors (
retryable: false). Fix the request instead.
Retry-After is longer than you want to wait (for example a sending limit that resets at midnight), schedule the send for later. An idempotency key is honored for 24 hours. See Idempotency.
Common questions
Are request limits per key or per workspace?
Are request limits per key or per workspace?
Per API key. A workspace has one key today, so that is the same thing.
Do cached capability checks count against the quota?
Do cached capability checks count against the quota?
No. Only fresh checks count toward the 30 per hour and 100 per day. A cached answer has
source: "cached".Why did a send return 429 when I'm well under 120 writes a minute?
Why did a send return 429 when I'm well under 120 writes a minute?
The number hit a sending limit, not the API. Check
error.details[0].limit_type and scope. See Phone numbers and limits.Why did my second message to someone return 400, not 429?
Why did my second message to someone return 400, not 429?
That is a sending rule, not a rate limit: links, attachments, contact cards and texts over 300 characters are rejected until the contact replies, and at most 6 texts go out in a row without a response. These are never retryable. See Sending rules.
Next steps
Phone numbers and limits
Sending limits and the live fields that report them.
Sending rules
What a message can contain before and after a reply.
Idempotency
Retry without sending twice.