Network and rate limits

Two network rules apply to every production key: requests must come from the IP addresses you registered with Octane, and a key may make at most 60 requests per minute. Both are enforced before a request reaches the API, so a blocked request gets a short JSON error and nothing else.

IP allow-listCopy Anchor Link

Every production key is pinned to an allow-list of IP addresses or CIDR ranges that you supply. Requests from any other source address are rejected:

HTTP/1.1 403 Forbidden
{ "error": { "code": "IP_NOT_ALLOWED" } }

• Provide the public egress IPs of the systems that call the API. If you run behind a NAT gateway or a cloud provider, that is the gateway's address, not the internal one.
• Individual IP addresses and CIDR ranges are accepted.
• Changes to the allow-list go through Octane. Send the new addresses to your account manager ahead of any infrastructure change; the update is applied on Octane's side and is not instantaneous.
• The allow-list applies only to the Pull API. Webhooks are outbound from Octane and are not affected.
• Staging keys are not restricted by IP.

Rate limitCopy Anchor Link

Each key may make 60 requests per 60-second window. The 61st request in a window is rejected until the window resets:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{ "error": { "code": "RATE_LIMITED" } }

• The limit is per key. Do not rely on spreading requests across several IP addresses to get more capacity.
• There is no separate daily quota.
• Octane can configure a different limit for a key on request, if your integration has a justified need.

What should I do on a 429?Copy Anchor Link

Respect the Retry-After header (seconds) and wait at least that long before retrying. A simple pattern:

async function octaneFetch(url, options, attempt = 0) {
  const res = await fetch(url, options);
  if (res.status === 429 && attempt < 5) {
    const retryAfter = Number(res.headers.get('Retry-After') ?? 60);
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    return octaneFetch(url, options, attempt + 1);
  }
  return res;
}

How do I stay under the limit?Copy Anchor Link

• Use limit=100 when paging through history to minimise the number of requests.
• Sync on a schedule rather than polling continuously. A sync every 15 minutes over the last hour is a typical pattern.
• Prefer webhooks for near-real-time needs and use the Pull API for reconciliation.
• Run one sync process at a time per key; parallel workers sharing a key will exhaust the limit quickly.