Rate limits & credits

There are two separate meters and they fail differently. Rate is how fast you may ask; quota is how much you may consume in a billing period. Hitting either returns 429, but only one of them is worth retrying.

The limits themselves

Rate is per account, not per key: adding keys does not add throughput. The full plan comparison is on pricing.

Three of those columns do different jobs. Requests per second is the pace. In flight is how many answers you may be waiting for at once, and on a paid plan it is the limit you are most likely to meet first: a worker pool of thirty threads hits it long before it hits the rate. Credits is the budget for the period.

The trial is the one row where credits are a *stock* rather than a rate: they are granted once and do not renew, so its daily cap is a brake against burning the whole trial in one loop rather than an anti-mirror control. The paid plans have no daily cap at all.

Until you see them, model the meter on your side: count your own calls against the cost table below, and treat a 429 as the authoritative signal rather than as a surprise.

The three 429s

Quota exhaustion is 429 and not 402 deliberately. Gateways, CDNs and corporate proxies handle 402 unpredictably — some cache it, some rewrite it — and an ambiguous status on the one response that costs a customer money is not a place to be clever.

Backing off correctly

Because no header tells you where you stand, the backoff has to work from the response alone. Honour Retry-After when it is there, fall back on exponential delay when it is not, and add jitter so a fleet of your own workers does not resynchronise into a thundering herd:

async function call(url: string, key: string, attempt = 0): Promise<Response> {
  const res = await fetch(url, { headers: { "X-Api-Key": key } });
  if (res.status !== 429) return res;

  const { error } = await res.clone().json();
  // Nothing recovers a spent quota except time. Fail loudly instead of
  // spending the next hour proving it.
  if (error.code === "QUOTA_EXCEEDED") throw new Error("quota exhausted");
  if (attempt >= 5) throw new Error(error.code);

  // Retry-After may be absent. Never let a missing header collapse the
  // delay to zero — that turns a rate limit into a hot loop.
  const advertised = Number(res.headers.get("Retry-After") ?? 0) * 1000;
  const backoff = Math.max(advertised, 2 ** attempt * 250);
  await new Promise((r) => setTimeout(r, backoff + Math.random() * 250));

  return call(url, key, attempt + 1);
}

What a request costs

Credits are per operation, not per row. A search that returns 250 cards costs the same as one that returns 3 — so a larger limit is strictly cheaper than more requests, up to the ceiling of 250.

Cheaper by construction

Two habits cut most bills in half: send If-None-Match so unchanged pages return 304, and ask only for the select fields you actually render. Both reduce what you spend without changing anything your users see.