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 class | Per 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 |
| finance | 300 |
| webhooks management | 300 |
| 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.
| Kind | Per 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:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Ceiling for the bucket that was checked |
X-RateLimit-Remaining | Remaining requests in the current window |
X-RateLimit-Reset | Unix timestamp (seconds) when the window resets |
X-RateLimit-Bucket | The bucket the three numbers belong to, <class>:<kind> |
Retry-After | Seconds 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 a403for 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-iptakes no key either but is limited per calling address, and does carry the three headers. - A sandbox
429simulated withX-Avrix-Sandbox-Simulate: rate_limit. It is answered before the request is counted, so it rehearsesRetry-Afteronly.
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#
- Back off on 429 using
Retry-After(cap your sleep; add jitter). - Prefer ETag / conditional GETs and the published catalog sync pattern — Caching and fairness.
- Do not busy-poll
GET /ordersor availability in a tight loop; use webhooks plus a slower reconciliation job. - Hot-drop reserve/commit is for vendor-declared launches — see Hot drop.
Related#
- Error reference —
RATE_LIMIT_EXCEEDED - Partner runbook
- Caching and fairness