Rate limits

The API request limit and how to handle 429 responses.

The API allows 200 requests per minute per account. Go over and you'll get 429 Too Many Requests until the window clears. The window is a fixed minute: the full 200 come back at once when it resets. Every response carries X-Rate-Limit-Remaining, so you can see how close you are.

Sending one message per request is fine, and many integrations work that way. When the same message goes to a large list at once, a group send or a batch call can turn thousands of requests into one: one call sends to a whole group, one call upserts a batch of contacts, and one report covers every recipient.

Two different limits

The request limit (this page) is how many HTTP calls you can make per minute. Delivery throughput (how fast messages actually reach handsets) is a separate property of your sending number and its registration (10DLC trust score, toll-free verification, short code), and is unaffected by how you call the API. A group send to 50,000 contacts is one request against the limit; how quickly those 50,000 deliver is throughput.


What a 429 looks like

HTTP/1.1 429 Too Many Requests
X-Rate-Limit-Remaining: 0
X-Rate-Limit-Retry-After-Milliseconds: 4213
Retry-After: 4

There's no JSON body. X-Rate-Limit-Retry-After-Milliseconds tells you how long to wait before the next request will be accepted, in milliseconds; the standard Retry-After header carries the same wait in whole seconds.

Handle it by sleeping for that long and retrying:

import time, requests

def ez_call(method, url, **kw):
    while True:
        resp = requests.request(method, url, **kw)
        if resp.status_code != 429:
            return resp
        wait_ms = int(resp.headers.get("X-Rate-Limit-Retry-After-Milliseconds", 1000))
        time.sleep(wait_ms / 1000)
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function ezCall(url, init) {
  while (true) {
    const res = await fetch(url, init);
    if (res.status !== 429) return res;
    await sleep(Number(res.headers.get("X-Rate-Limit-Retry-After-Milliseconds") ?? 1000));
  }
}
<?php
function ezCall(string $method, string $url, array $opts): array {
    while (true) {
        // your HTTP helper
        [$status, $headers, $body] = httpRequest($method, $url, $opts);
        if ($status !== 429) {
            return [$status, $body];
        }
        usleep((int) ($headers['x-rate-limit-retry-after-milliseconds'] ?? 1000) * 1000);
    }
}
def ez_call(req, uri)
  loop do
    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
    return res unless res.code == "429"
    sleep((res["X-Rate-Limit-Retry-After-Milliseconds"] || "1000").to_i / 1000.0)
  end
end
HttpResponse<String> ezCall(HttpRequest request) throws Exception {
    while (true) {
        HttpResponse<String> res = client.send(request, HttpResponse.BodyHandlers.ofString());
        if (res.statusCode() != 429) return res;
        long waitMs = res.headers().firstValue("X-Rate-Limit-Retry-After-Milliseconds").map(Long::parseLong).orElse(1000L);
        Thread.sleep(waitMs);
    }
}
async Task<HttpResponseMessage> EzCallAsync(Func<HttpRequestMessage> makeRequest)
{
    while (true)
    {
        var res = await client.SendAsync(makeRequest());
        if (res.StatusCode != HttpStatusCode.TooManyRequests) return res;
        var waitMs = res.Headers.TryGetValues("X-Rate-Limit-Retry-After-Milliseconds", out var v) ? int.Parse(v.First()) : 1000;
        await Task.Delay(waitMs);
    }
}
func ezCall(makeReq func() *http.Request) (*http.Response, error) {
	for {
		resp, err := http.DefaultClient.Do(makeReq())
		if err != nil || resp.StatusCode != 429 {
			return resp, err
		}
		resp.Body.Close()
		waitMs, _ := strconv.Atoi(resp.Header.Get("X-Rate-Limit-Retry-After-Milliseconds"))
		if waitMs <= 0 {
			waitMs = 1000
		}
		time.Sleep(time.Duration(waitMs) * time.Millisecond)
	}
}

Add a cap on total attempts in production so a persistent problem doesn't become an infinite loop. Errors has a fuller retry policy that also covers 5xx.


Staying under the limit

The limit is per request, not per message. If you're getting close to it, these patterns cut the number of requests:

Common patternFewer requestsRequests
The same message sent with one POST /v1/messages per recipientPut the numbers in one toNumbers array, or add the contacts to a group and send to groupIds1
One POST /v1/contacts per contactPOST /v1/contacts/batch with many contacts1 per batch
Polling GET /v1/message-reports/{id} in a tight loopPoll every 30–60 s with backoff; delivery takes seconds to minutes anywayA few
Polling for inbound textsSubscribe a webhook; sweep with GET /v1/conversations?filters[unread][eq]=true only as a fallback~0
Fetching contacts one by oneGET /v1/contacts with size=200 and page through1 per 200
Checking credits before every sendCheck once a minute, or once per batch~1/min

A single group send to 50,000 contacts is one request. Personalize it with merge tags and you still have 199 requests left in the minute, while the messages themselves drain at whatever rate your number type supports.


Client-side throttling

If you have many workers calling the API, add a shared token bucket so you never send 201 requests in a minute in the first place. A simple version: a Redis counter keyed by the current minute, incremented before each call, with callers sleeping until the next minute when it passes ~180 (leave headroom for retries and other processes).

For a single process, a sleep of 350 ms between calls keeps you near 170/min, under the limit with no bookkeeping.


Transactional traffic at scale

OTP and notification sends are inherently one-request-per-event, so the request limit is the ceiling that matters for them. As pure request arithmetic, 200 requests/minute sustained around the clock is 288,000 single-recipient calls per day, but that is arithmetic, not a delivery figure, and real traffic is bursty: what you need is headroom at your peak minute. If your peak approaches 200 single sends a minute, contact your EZ Texting account manager. Don't try to work around the limit with multiple accounts.


Related


Did this page help you?