Rate limits

The API limits how many requests a credential can make per minute. Limits are counted per deploy token, so two tokens on the same project each have their own budget.

The limitsCopy Anchor Link

Push and cancel draw on budgets of their own, so they never compete with the general one:

• A repository upload is one push per file, so a project with many locale files can upload them all without touching the budget your status checks use.
• Polling a batch never uses up the requests you need to cancel it.

HeadersCopy Anchor Link

Responses from a limited endpoint carry the current state of the limit:

When you exceed a limit, the answer is 429 with the problem type /problems/rate-limited:

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 42
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1791820920

{"type":"/problems/rate-limited","title":"Rate limited","status":429,"detail":"Too many requests."}

Backing offCopy Anchor Link

Wait for Retry-After when it is present. When it is not (a 5xx, or a dropped connection), back off exponentially with jitter, and give up after a few attempts.

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

export async function requestWithBackoff(url: string, init: RequestInit, attempts = 5): Promise<Response> {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(url, init);

    const retryable =
      res.status >= 500 ||
      (res.status === 429 && (await res.clone().json()).type === '/problems/rate-limited');

    if (!retryable || attempt === attempts - 1) return res;

    const retryAfter = Number(res.headers.get('Retry-After'));
    const delay = retryAfter > 0
      ? retryAfter * 1000
      : Math.min(30_000, 1000 * 2 ** attempt) + Math.random() * 250;

    await sleep(delay);
  }
}

Recent versions of curl honour Retry-After on a 429 when you ask them to retry:

curl --retry 4 --retry-max-time 120 \
  https://api.transglot.ai/v1/batches/4822 \
  -H "Authorization: Bearer $TRANSGLOT_TOKEN"

Staying under the limitsCopy Anchor Link

• Poll with backoff. When you watch a batch, start at one second and double the interval up to about fifteen. A run takes minutes, not seconds.
• Use webhooks instead of polling. Subscribe an endpoint to batch.completed and batch.failed and you need no status requests at all. See Webhooks.
• Read many values at once. POST /v1/translations/batch reads up to 1,000 keys in one request where GET /v1/translations reads one.
• Revalidate instead of downloading. Send the ETag you have as If-None-Match on GET /v1/pull and the CDN reads. A 304 is still a request, but it carries no body.
• One token per pipeline. Each token has its own budget, so a busy CI pipeline does not slow down another job that uses a different token.

The command line tool already waits for Retry-After and backs off while it polls.

RelatedCopy Anchor Link

• Errors
• Authentication
• Connect your app to the CDN