Rate Limits

The limits

Each window is a fixed 60-second window that resets once it elapses. The default 100/60s limit applies to the API data plane and is not split by read vs. write. A small set of sensitive authentication and security endpoints (such as sign-in, password reset, and email verification) carry tighter per-route limits to protect your account. The limits are the same in sandbox and production.

Requests are counted per API key (your client ID). Requests that arrive without credentials are counted per source IP address instead. If you need a higher limit, contact us at support@billerapi.com.

Rate limit headers

Every response — not just 429s — carries your current budget so you can throttle yourself before you ever hit the limit:

A successful response looks like this:

When you exceed the limit

The API returns 429 Too Many Requests with the RATE_LIMITED error code. The seconds to wait before retrying are surfaced two ways: the Retry-After response header and a numeric retry_after field in the JSON error body. Prefer the body field; fall back to the header.

Quote the request_id in any support request. See Error Handling for the full error envelope.

Backoff strategy

When you get a 429, wait the number of seconds in retry_after (or the Retry-After header) before retrying. If neither is present, fall back to exponential backoff with jitter. Never retry immediately.

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    if (attempt === maxRetries) {
      throw new Error('Max retries exceeded');
    }

    // Prefer the retry_after body field, then the Retry-After header,
    // then exponential backoff.
    let delaySeconds;
    try {
      const body = await response.clone().json();
      delaySeconds = typeof body.retry_after === 'number' ? body.retry_after : undefined;
    } catch {
      delaySeconds = undefined;
    }
    if (delaySeconds === undefined) {
      const header = response.headers.get('Retry-After');
      delaySeconds = header ? parseInt(header, 10) : Math.min(Math.pow(2, attempt), 30);
    }

    // Add jitter to prevent thundering herd.
    const jitter = Math.random() * 1000;
    await new Promise(resolve => setTimeout(resolve, delaySeconds * 1000 + jitter));
  }
}

Best practices

• 1.Watch the headers — read X-RateLimit-Remaining on every response and slow down as it approaches zero, rather than waiting for a 429.
• 2.Use webhooks instead of polling — subscribe to events like bill.created instead of polling for new bills.
• 3.Cache and batch — biller metadata and account details change infrequently; cache them, and fetch multiple records in a single paginated request instead of one-by-one.
• 4.Always back off — never retry immediately after a 429. Wait at least the retry_after duration.

Related

• Error Handling — error response format and codes
• Authentication — API key and bearer token auth
• Webhooks — event-driven alternative to polling