Rate limiting

Wajub throttles on several axes at once: your account, the individual key, and a few sensitive endpoints, or the calling IP when a request carries no key. A request needs to clear all of them. Whichever one trips first decides your 429.

The limits

Sandbox and live are counted apart. Each gets the whole of the ceilings above, so a load test run with a sandbox key never spends the minute of your live checkout. The API key row needs nothing for that: a sandbox key and a live key are two keys.

Read the limit, do not hardcode it

Your account quota depends on your plan and on any custom ceiling support has set for you. Rather than mirroring a table that can change under you, read it back from every response:

X-RateLimit-Limit: 360
X-RateLimit-Remaining: 357
X-RateLimit-Reset: 1748083260

These three headers describe the account counter only. The per-key, per-IP and per-endpoint counters are not exposed, so a 429 can arrive while X-RateLimit-Remaining still looks healthy. The type field in the body says which one it was.

What a 429 looks like

Read type before you react. A team or api_key 429 means slow down everywhere; an endpoint one means only that resource is saturated and the rest of your traffic can continue; an ip one means the call went out without a key.

From a browser

A page calling the API with a public key can read every answer, the 429 included: it carries the CORS headers like any other response. The page's code can read Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-Wajub-Version, so it can wait the time the API asks for instead of guessing.

The tighter throttles, such as the one on payout writes, answer with the same body: type names the throttle (payout_writes), and retry_after and the Retry-After header give the real wait. Treat any 429 the same way: read retry_after, wait, retry.

Backing off

Honour Retry-After when it is there, fall back to exponential back-off with jitter when it is not. Jitter matters: without it, every worker throttled at the same second retries at the same second.

async function withRetry(send, max = 3) {
for (let attempt = 0; ; attempt++) {
  const res = await send();

  if (res.status !== 429 || attempt >= max) return res;

  const header = Number(res.headers.get('retry-after'));
  const wait = Number.isFinite(header) && header > 0
    ? header
    : 2 ** attempt * (0.5 + Math.random() * 0.5);

  await new Promise((r) => setTimeout(r, wait * 1000));
}
}

The PHP example reuses the same $options, and therefore the same idempotency key, so the retry cannot create a second payment. See Idempotency.