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.
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
429 looks likeHTTP/1.1 429 Too Many Requests
X-Rate-Limit-Remaining: 0
X-Rate-Limit-Retry-After-Milliseconds: 4213
Retry-After: 4There'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
endHttpResponse<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 pattern | Fewer requests | Requests |
|---|---|---|
The same message sent with one POST /v1/messages per recipient | Put the numbers in one toNumbers array, or add the contacts to a group and send to groupIds | 1 |
One POST /v1/contacts per contact | POST /v1/contacts/batch with many contacts | 1 per batch |
Polling GET /v1/message-reports/{id} in a tight loop | Poll every 30–60 s with backoff; delivery takes seconds to minutes anyway | A few |
| Polling for inbound texts | Subscribe a webhook; sweep with GET /v1/conversations?filters[unread][eq]=true only as a fallback | ~0 |
| Fetching contacts one by one | GET /v1/contacts with size=200 and page through | 1 per 200 |
| Checking credits before every send | Check 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
- Errors
- Idempotency & retries
- Core concepts — group sends and batch upserts
Try Troubleshooting, check status.eztexting.com, or contact support.
Updated 3 days ago