Rate limits

The three headers

An answer to a request without a valid credential does not carry them.

What is limited

• The limit is the account's: all its keys share it.
• There are two limits: requests over time, and calls in progress at once.
• The limit in force is what the headers and GET /v1/account (its rate) say. It rises with an account's first top-up.
• The free routes with a key (/v1/account, /v1/usage, /v1/calls/…) draw on a separate count, so looking a call up never takes from the calls you pay for. The headers on those answers speak of that count.

curl "https://api.dataxapi.com/v1/account" \
  -H "Authorization: Bearer $DATAXAPI_API_KEY"

Over the limit

A request over the limit gets 429 rate_limited at once. It did not run and is not charged. reason says which limit it was.

When the platform a call reads from is limiting us, the answer is 503 upstream_busy: not charged, and it carries Retry-After when a wait can be named.

Retrying

The SDKs retry by themselves: twice by default (maxRetries, in Python max_retries), only what the service says may be retried, waiting as long as it says. A wait longer than a minute is not waited out: the error is thrown with the wait on it.

Over plain HTTP, the same in a few lines:

// One key for the call and every retry of it: a retry is then never charged twice.
const key = crypto.randomUUID();

async function call(url: string): Promise<unknown> {
  for (let attempt = 0; ; attempt += 1) {
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.DATAXAPI_API_KEY}`, "Idempotency-Key": key },
    });
    const body = await response.json();
    if (response.ok) return body;
    if (body.retry !== "yes" || attempt >= 2) throw new Error(body.code);
    // The wait the service names, or 1, 2, 4 seconds when it names none.
    const seconds = body.retry_after_seconds ?? 2 ** attempt;
    await new Promise((done) => setTimeout(done, seconds * 1000));
  }
}