Rate limits

Per-tier request ceilings, headers, and Retry-After guidance.

TopicsOperate

There are no rate-limit plans or tiers on the Seller API.

Production keys: fair-use limits per key#

A production key has generous limits per route class, counted per key on a one-minute sliding window. They exist to stop runaway polling loops, not to meter normal traffic:

Route classPer minute per key
catalog (products, pricing, availability, snapshot, changes)600 full reads; 6,000 cheap pre-flights (a 304 or cache HIT does not use the full-read budget)
orders (preview, hold, orders, bulk, key pull, export and return, refunds, transactions, allocation requests)1,200
finance300
webhooks management300
general (everything else)600

API-key management (GET and POST /keys, DELETE /keys/{id}, POST /keys/{id}/rotate, PATCH /keys/{id}/allowed-ips) is counted in general on contract date 2026-12-01 and later, so a key-inventory job no longer spends the checkout budget. Earlier contract dates count it in orders.

Each operation in the OpenAPI document (GET /api/seller/v1/openapi) states its class in x-avrix-rate-limit-class (and x-avrix-rate-limit-class-2026-12-01 where it depends on the contract date). none means the operation reads no key and is not counted against a key's budget. x-avrix-tier is a functional grouping, not a budget.

A full GET /catalog/snapshot body counts against an extra budget of 6 per hour per key. A mirror should seed from one snapshot and then follow GET /catalog/changes; a revalidation with If-None-Match that answers 304 is free.

Launch headroom on one key. If a launch or hot drop needs more orders-class calls on a single key than the table allows, ask Avrix before the launch. A platform admin can raise the orders limit for that key, optionally only for the launch window; outside the window the default applies again. The limit that applies to a request is always the one in X-RateLimit-Limit.

Shadow mode first. The limits are live in the X-RateLimit-* headers, but while GET /whoami reports data.key.rateLimitMode: "shadow", a request over a limit is still served and only logged on our side. When enforcement is switched on (rateLimitMode: "enforced"), an over-limit request answers 429 RATE_LIMIT_EXCEEDED with Retry-After. Any change to that is announced in the Changelog first.

Register an IP allowlist on every production key. Traffic that trips the edge network's own abuse protection receives an HTML 403 challenge before it reaches the API — see Error playbook. Keep bursts sane, send If-None-Match on catalog reads, and register every egress IP.

Sandbox keys: one flat abuse cap#

Sandbox keys all route to the shared sandbox catalog, which anyone can obtain a key for, so they keep a single protective cap. It is identical for every company and is not a plan.

KindPer minute (sliding window)
write (POST / DELETE / PATCH)600
read (GET doing fresh work)1,200
read-cached (cacheable catalog pre-flight; 304 / cache HIT does not debit read)12,000

Within a sandbox company the cap is split by route class (catalog, orders, finance, webhooks management, general) so one chatty surface cannot starve another. Exceeding the cap returns 429 RATE_LIMIT_EXCEEDED with Retry-After.

GET /whoami reports data.key.rateLimited (whether an over-limit request is refused), data.key.rateLimitMode (shadow or enforced) and data.key.rateLimits: every bucket of the calling key with its limit and window, from the same constants the limiter uses, plus any orders-class launch limit set for the key (ordersOverride).

Which budget a request spends from#

A budget, or bucket, is one route class and one kind: read, read-cached (a cacheable catalog pre-flight) or write. Production keys also have catalog:snapshot, the hourly budget for full snapshot bodies. Every response counted against a bucket names it in X-RateLimit-Bucket as <class>:<kind>, for example orders:write or catalog:read-cached. Two requests answered with the same value spend from the same budget. The numbers in the three X-RateLimit-* headers belong to that bucket.

Headers#

curl -s -X GET "https://api.avrix.io/api/seller/v1/whoami" \
  -H "Authorization: Bearer $AVRIX_API_KEY"

Responses include (and CORS exposes) these exact names:

HeaderMeaning
X-RateLimit-LimitCeiling for the bucket that was checked
X-RateLimit-RemainingRemaining requests in the current window
X-RateLimit-ResetUnix timestamp (seconds) when the window resets
X-RateLimit-BucketThe bucket the three numbers belong to, <class>:<kind>
Retry-AfterSeconds to wait before retrying (especially on 429)

Always prefer numeric Retry-After on 429s when present. A 429 from the limiter also repeats the bucket, the limit and the wait in its body: details.rateLimitBucket, details.limit and details.retryAfterSeconds.

Which responses carry them. Every response to a request that was counted against a limit carries all three X-RateLimit-* headers: a success, a 304, a validation or not-found error, a 5xx, a replayed idempotent response and a 429. You can pace a client on any route from X-RateLimit-Remaining and X-RateLimit-Reset alone. Three kinds of response carry none:

  • A request refused before it is counted: 401, and a 403 for a missing scope or an address outside the key's IP allowlist.
  • The routes that take no API key: GET /health, GET /openapi, GET /webhooks/egress-ips, the OAuth token exchange and the buyer-facing geo attestation calls. GET /whoami-ip takes no key either but is limited per calling address, and does carry the three headers.
  • A sandbox 429 simulated with X-Avrix-Sandbox-Simulate: rate_limit. It is answered before the request is counted, so it rehearses Retry-After only.

A response that reports a narrower budget keeps it: the full catalog snapshot reports its own hourly allowance in the same three headers. X-RateLimit-Bucket is sent only with numbers of the bucket it names, so it is absent where a response reports another budget's numbers, and on GET /whoami-ip, whose limit is per calling address.

Client guidance#

  1. Back off on 429 using Retry-After (cap your sleep; add jitter).
  2. Prefer ETag / conditional GETs and the published catalog sync pattern — Caching and fairness.
  3. Do not busy-poll GET /orders or availability in a tight loop; use webhooks plus a slower reconciliation job.
  4. Hot-drop reserve/commit is for vendor-declared launches — see Hot drop.

What links here

Published guides that link to this page.

Search docs

Search documentation…