Limits

The API limits the pace of calls, key by key. A call over the limit gets a 429 RATE_LIMITED. It costs no credit and tells you when to retry.

The limits of a key

Counters belong to each key: a chatty tool does not slow down the others. A write also counts in the two general limits. A read never counts in the last two. The kind of an operation is read in kind of GET /operations, not in the HTTP method, since every operation goes through POST.

Read a 429

HTTP/1.1 429 Too Many Requests
Retry-After: 1
RateLimit-Limit: 10
RateLimit-Remaining: 0
RateLimit-Reset: 1

The body is { "error": { "name": "PARTNER_API", "message": "RATE_LIMITED" } }. Retry-After gives the seconds to wait. The RateLimit-* headers tell you where you stand: the limit, what remains and the delay before the reset.

Resume after a 429

Wait Retry-After seconds, then retry. If the 429 comes back, wait longer each time: one, two, four seconds. For a write, keep the same Idempotency-Key: a 429 is never stored, so the retry runs.

The call function in Write a script already waits for Retry-After. The growing wait is for you to add, here is the principle:

Python

wait = 1
for _ in range(5):
    res = requests.request(method, url, headers=headers, json=body)
    if res.status_code != 429:
        break
    time.sleep(max(int(res.headers.get("Retry-After", 0)), wait))
    wait *= 2

JavaScript

let wait = 1;
for (let attempt = 0; attempt < 5; attempt++) {
  const res = await fetch(url, { method, headers, body });
  if (res.status !== 429) return res;
  const retryAfter = Number(res.headers.get("Retry-After") ?? 0);
  await new Promise((done) =>
    setTimeout(done, Math.max(retryAfter, wait) * 1000)
  );
  wait *= 2;
}

Stay under the limits

• Ask for limit=200 on lists and reread only the changes with since: Pagination.
• Spread your calls instead of firing them all at once: 10 per second is reached fast.
• Create one key per tool, so that each has its own counters.

A 429 is not a 402. The 429 comes from the pace and clears by itself. The 402 comes from an empty balance: see Keys and credits.