Rate limits

The BatchRouter API is rate-limited to keep the platform stable and fair across all accounts. Limits are enforced per API key and per account. When you exceed a limit, the API responds with HTTP 429 Too Many Requests; your client should back off and retry rather than hammering the endpoint.

This page explains how to detect rate limiting and how to handle it. For the current limits and any per-endpoint details, consult the interactive API reference and the response headers you receive at runtime.

How rate limiting works

Rate limits apply at two scopes:

• Per API key — each br_live_… key is metered independently.
• Per account — usage is also aggregated across all of an account’s keys.

Limits are enforced on request volume over a rolling window. BatchRouter is built for batch workloads, so the design intent is that you submit a small number of large batches rather than a high volume of tiny requests — a single POST /v1/batches call can carry many thousands of items, which is far more efficient than one request per item.

Note

This page intentionally does not quote fixed numeric limits, because they can change and may differ by endpoint. Treat a 429 response (and any rate-limit headers it carries) as the authoritative signal, and check the API reference for the values in effect for your account.

A few endpoints have their own dedicated, stricter limits — for example, registration endpoints are tightly throttled to deter abuse. Those constraints are documented alongside the relevant operation in the API reference.

The 429 response

When you exceed a limit, the API returns HTTP 429 Too Many Requests. The response may include a Retry-After header indicating how long to wait before retrying — in seconds, or as an HTTP date. Always prefer the value the server gives you over a fixed delay of your own.

Tip

Inspect response headers on every 429. If a Retry-After header is present, wait at least that long before retrying. Any additional rate-limit headers the response carries are the source of truth for your remaining budget.

Handling 429 with backoff

The correct response to a 429 is to wait and retry with exponential backoff and jitter: increase the delay on each successive failure, and add a small random offset so that many clients retrying at once don’t synchronize into a new spike. If a Retry-After header is present, honor it as the minimum wait.

cURL

cURL doesn’t loop on its own, so back off in your shell. This retries up to five times, honoring Retry-After when present and otherwise doubling the delay:

url="https://api.batchrouter.com/v1/batches"
delay=1
for attempt in $(seq 1 5); do
  response=$(curl -s -w "\n%{http_code}" -D /tmp/headers.txt "$url" \
    -H "Authorization: Bearer $BATCHROUTER_API_KEY")
  code=$(printf '%s' "$response" | tail -n1)
  if [ "$code" != "429" ]; then
    printf '%s\n' "$response" | sed '$d'
    break
  fi
  retry_after=$(grep -i '^retry-after:' /tmp/headers.txt | awk '{print $2}' | tr -d '\r')
  wait=${retry_after:-$delay}
  echo "429 received; waiting ${wait}s before retry $attempt" >&2
  sleep "$wait"
  delay=$((delay * 2))
done

Node

const BASE_URL = 'https://api.batchrouter.com';

async function requestWithBackoff(path, init = {}, maxRetries = 5) {
  let delayMs = 1000;
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(`${BASE_URL}${path}`, {
      ...init,
      headers: {
        Authorization: `Bearer ${process.env.BATCHROUTER_API_KEY}`,
        ...init.headers,
      },
    });

    if (res.status !== 429) return res;

    // Honor Retry-After (seconds) when present, else exponential backoff with jitter.
    const retryAfter = Number(res.headers.get('retry-after'));
    const wait = Number.isFinite(retryAfter) && retryAfter > 0
      ? retryAfter * 1000
      : delayMs + Math.random() * 250;

    await new Promise((r) => setTimeout(r, wait));
    delayMs *= 2;
  }
  throw new Error('Rate limited: retries exhausted');
}

const res = await requestWithBackoff('/v1/batches');
console.log(await res.json());

Python

import os
import random
import time
import requests

BASE_URL = "https://api.batchrouter.com"

def request_with_backoff(path, *, method="GET", max_retries=5, **kwargs):
    headers = {"Authorization": f"Bearer {os.environ['BATCHROUTER_API_KEY']}"}
    headers.update(kwargs.pop("headers", {}))

    delay = 1.0
    for attempt in range(max_retries + 1):
        res = requests.request(method, f"{BASE_URL}{path}", headers=headers, **kwargs)
        if res.status_code != 429:
            return res

        # Honor Retry-After (seconds) when present, else exponential backoff with jitter.
        retry_after = res.headers.get("Retry-After")
        wait = float(retry_after) if retry_after and retry_after.isdigit() else delay + random.random() * 0.25
        time.sleep(wait)
        delay *= 2

    raise RuntimeError("Rate limited: retries exhausted")

res = request_with_backoff("/v1/batches")
print(res.json())

Practical guidance

• Batch, don’t spray. Put many items into one POST /v1/batches request instead of issuing one request per item. This is the single biggest factor in staying under any limit.
• Poll on a sensible interval. When checking batch status with GET /v1/batches/{batchId}, poll periodically (for example, every few seconds for fast lanes, less often for flex) rather than in a tight loop. Prefer webhooks to learn about completion instead of aggressive polling where you can.
• Always honor Retry-After. Treat the server’s wait hint as a hard minimum.
• Add jitter. Randomize backoff slightly so concurrent workers don’t resynchronize into a new burst.
• Cap your retries. After a reasonable number of attempts, surface the failure to your own error handling rather than retrying forever.

Caution

Rate limiting (429) is distinct from a funding or quota rejection. A request that fails because your account is out of credits or hits a billing control is not a 429 — see Errors to tell the responses apart and respond appropriately.

Next steps

Errors The full error model, including how 429 differs from billing and validation failures.

Idempotency and retries Safely retry batch submissions with an Idempotency-Key and receive completion via webhooks.

API reference Interactive Scalar reference with the current limits and per-endpoint details.