Bankworks

Rate limits

Every account starts at 10 requests per second with a burst of 20. Higher limits are granted per account — ask, and tell us the shape of your traffic.

What counts

Every authenticated /v1 request: submitting a job, polling it, downloading HTML, reading your balance. Polling is not free, which is the main thing to design around.

The limit is applied per account, not per key. Issuing ten keys to ten machines does not give you ten times the limit — they share one allowance.

How the limit behaves

A token bucket, not a fixed window. The bucket holds up to burst tokens and refills continuously at rps per second. Each request spends one.

Headers

HeaderOnMeaning
X-RateLimit-Limitevery responseYour sustained requests per second
X-RateLimit-Remainingevery responseWhole tokens left in the bucket
Retry-After429 onlySeconds until one token exists

Being limited

HTTP
HTTP/1.1 429 Too Many Requests
Retry-After: 2

{"ok": false, "code": "rate_limited", "limitRps": 10,
 "retryAfterSeconds": 2,
 "error": "Rate limit exceeded: 10 request/second for this account…"}
Honour Retry-After. It is rounded up to the next whole second, so a client that waits exactly that long never comes back early and never burns a second rejection. Retrying immediately in a loop is how an account spends its whole allowance on rejections.

A client that does exactly that, for both 429 and 503:

Python
import os
import time

import requests

API = os.environ.get("API", "https://bankworks.info")
http = requests.Session()
http.headers["Authorization"] = f"Bearer {os.environ['API_KEY']}"


def call(method, path, attempts=6, **kwargs):
    """Send a request, waiting out 429 and 503 exactly as long as the server asks."""
    for attempt in range(1, attempts + 1):
        response = http.request(method, f"{API}{path}", timeout=30, **kwargs)
        if response.status_code not in (429, 503):
            return response
        # Retry-After is whole seconds, rounded up, so waiting exactly this long
        # never comes back early and never spends a second rejection.
        wait = max(1, int(response.headers.get("Retry-After", "1")))
        print(f"{response.status_code}: waiting {wait}s (attempt {attempt}/{attempts})")
        time.sleep(wait)
    raise RuntimeError(f"still limited after {attempts} attempts")


response = call("GET", "/v1/me")
response.raise_for_status()
print("ok:", response.json()["principal"]["name"])
Node.js
const API = process.env.API ?? "https://bankworks.info";
const API_KEY = process.env.API_KEY;
if (!API_KEY) throw new Error("Set API_KEY first");

const sleep = (seconds) => new Promise((done) => setTimeout(done, seconds * 1000));

// Send a request, waiting out 429 and 503 exactly as long as the server asks.
async function call(path, options = {}, attempts = 6) {
  for (let attempt = 1; attempt <= attempts; attempt += 1) {
    const response = await fetch(`${API}${path}`, {
      ...options,
      headers: { Authorization: `Bearer ${API_KEY}`, ...options.headers },
    });
    if (response.status !== 429 && response.status !== 503) return response;

    // Retry-After is whole seconds, rounded up, so waiting exactly this long
    // never comes back early and never spends a second rejection.
    const wait = Math.max(1, Number(response.headers.get("retry-after") ?? 1));
    console.log(`${response.status}: waiting ${wait}s (attempt ${attempt}/${attempts})`);
    await sleep(wait);
  }
  throw new Error(`still limited after ${attempts} attempts`);
}

const response = await call("/v1/me");
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log("ok:", (await response.json()).principal.name);
cURL
# curl waits for Retry-After on 429 and 503 by itself when --retry is set.
curl -sS --retry 5 --fail-with-body \
  -H "Authorization: Bearer $API_KEY" \
  "$API/v1/me"

Designing inside the limit

At 10/s a single client can comfortably run a 1,000-URL job and poll it every 3 seconds while downloading results in parallel. If you are hitting the limit with that pattern, something is retrying in a loop.

Getting a higher limit

Limits are set per account by an operator. Tell us your peak requests per second, whether it is steady or bursty, and the volume of pages per day — the limit is then set from the shape of the traffic rather than guessed.