Rate limits

Limits are per team, not per key. Adding keys does not add throughput.

The limits

Headers

Every response carries your current budget:

X-RateLimit-Limit: 25
X-RateLimit-Remaining: 21
X-RateLimit-Reset: 1

X-RateLimit-Reset is in seconds. When the limit is hit you get 429 with the code rate_limited and a Retry-After header, also in seconds.

How the window works

The limiter is a sliding window over one second. There is no burst allowance and no token bucket to save up: at 25 requests per second you may send 25 requests in any one-second window, not 250 once every ten seconds.

Sizing your client

Concurrency of roughly the limit works well, because a translation request takes noticeably longer than a second is long. A worker pool of 20 against a limit of 25 will keep the pipe full without tripping the limiter.

Two habits prevent almost every 429:

1. Batch. Fifty texts in one request count as one request against the rate

limit. A loop over fifty single-text requests counts as fifty.

1. Back off on 429. Wait Retry-After seconds, then retry. Do not retry

immediately, and do not retry in a tight loop across all workers at once — add jitter.

Batching and the character limit

Batching interacts with the per-request character limit. Fifty texts of 5,000 characters is 250,000 characters, which is over every plan limit. Build batches by character count, not by item count:

def batches(texts, max_chars, max_items=50):
    batch, size = [], 0
    for text in texts:
        if batch and (size + len(text) > max_chars or len(batch) == max_items):
            yield batch
            batch, size = [], 0
        batch.append(text)
        size += len(text)
    if batch:
        yield batch

What a 429 does not do

A rate-limited request is rejected before anything is reserved: no characters are counted, no credit is spent, no usage event is written. A 429 is free.

Rate limits versus quota

They are different mechanisms and produce different errors.