R2 Connect API

Rate limits

How many requests you may make, how to know how many are left and what to do if you exceed them.

The limit is 600 requests per minute per key. It is a per-key limit, not shared across integrations: one system’s usage does not affect another, even if they serve the same business.

Headers on every response#

Header	Meaning
`X-RateLimit-Limit`	Requests allowed per minute.
`X-RateLimit-Remaining`	Requests left in the current window.
`X-RateLimit-Reset`	When the window resets, in epoch seconds.
`Retry-After`	Only on `429` responses: seconds you must wait.
`X-Request-Id`	Unique request identifier. Include it if you report a problem.

When you exceed the limit#

The response is 429 with code rate_limited. Wait the seconds given in Retry-After and retry; do not retry immediately or in a tight loop.

javascript

// Retry that honors Retry-After
async function request(url, options, attempts = 3) {
  for (let i = 0; i < attempts; i++) {
    const res = await fetch(url, options);
    if (res.status !== 429) return res;

    const wait = Number(res.headers.get("Retry-After") ?? 5);
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
  throw new Error("Rate limit exceeded after several attempts");
}

How to stay well under#

Request limit=50 instead of many small pages: fewer requests for the same data.
Sync incrementally with created_from since your last run, instead of re-reading the whole history.
Cache what you already read in your own system; catalog and customers change slowly.
Schedule large loads outside the business’s operating hours.

PreviousPagination & filters NextErrors