Rate limits

Limits protect every store on the platform from a single runaway client. They are counted in fixed one-minute windows and, depending on the endpoint, per client IP, per key or per person. Some endpoints have two limits at once — for example per IP and per publishable key — and a request must stay within both.

Public endpoints that shoppers' browsers call count per shopper IP, so a busy storefront does not run out: each visitor has their own allowance.

This table is built from the API specifications. The endpoint's reference page explains any extra rule (for example the returns lookup locks an order number after 5 failed attempts in 15 minutes).

Over the limit, Nucleo answers 429 Too Many Requests. Most endpoints add:

Where the header is missing, the body carries the wait in retry_after. Wait at least that long, then retry with exponential backoff and a little jitter:

async function withRetry(doRequest, attempts = 5) {
  for (let i = 0; i < attempts; i++) {
    const res = await doRequest();
    if (res.status !== 429 && res.status < 500) return res;
    const header = Number(res.headers.get("Retry-After"));
    const body = res.status === 429 ? await res.clone().json().catch(() => ({})) : {};
    const wait = (header || body.retry_after || 2 ** i) * 1000 + Math.random() * 250;
    await new Promise((r) => setTimeout(r, wait));
  }
  throw new Error("Nucleo API: too many retries");
}

<?php

function withRetry(callable $doRequest, int $attempts = 5)
{
    for ($i = 0; $i < $attempts; $i++) {
        $res = $doRequest();
        $status = $res->getStatusCode();
        if ($status !== 429 && $status < 500) {
            return $res;
        }
        $wait = (int) $res->getHeaderLine('Retry-After') ?: 2 ** $i;
        usleep(($wait * 1000 + random_int(0, 250)) * 1000);
    }
    throw new RuntimeException('Nucleo API: too many retries');
}

• Batch. The Collector accepts up to 50 events per request; send them together.
• Cache. The delivery promise is already cached by Nucleo for the time the merchant chose; cache CMS content on your side and refresh it on the revalidate webhook.
• Poll calmly. Warehouse interfaces are designed for polling every few minutes, not every second.
• Do not retry 4xx errors other than 429: the same request will fail the same way.