Rate limits
Per-key limits you can read at runtime, usage headers on responses, and a 429 policy your agent can follow mechanically.
Know your limit before you hit it
GET /v1/account/auth returns rate_limit_per_minute for the calling key — read it at startup instead of hardcoding. That per-minute rate limit is a separate thing from the monthly quota: the paid plan ships 50,000 API calls/month, with usage headers in responses and a projection from GET /v1/account/usage. A third limit, the Direct-AI evaluation allowance of 10 calls/day, applies only to the public assistant surface. All three are listed together in Limits.
The headers on every response
You never have to count requests yourself. Every response carries where you stand:
X-Quota-Hourly-Limit,X-Quota-Hourly-Used,X-Quota-Hourly-Remaining— the rolling hourly windowX-Quota-Hourly-Reset-At— RFC 3339 instant the hourly window resetsX-Quota-Limit,X-Quota-Used,X-Quota-Remaining— the monthly plan quotaX-Quota-Reset-At— RFC 3339 instant the monthly quota resetsX-Quota-Warning—none, or a level once you approach the monthly limit
On a sandbox key the hourly quota is what actually binds, not the per-minute figure.
A self-serve sandbox is capped at 200 requests an hour by default, while rate_limit_per_minute
reports 120 — nominally 7,200 an hour. Plan against X-Quota-Hourly-Remaining: running the
examples in a loop reaches the hourly cap long before the per-minute one, which is the usual reason an
evaluation starts returning 429 after a couple of minutes.
Paid tenants have no hourly cap at all — the per-minute limit is the real constraint there, and the
X-Quota-Hourly-* headers are absent rather than zero.
On 429
A 429 carries Retry-After, in seconds. Honour it. Blind exponential
backoff either waits longer than it needs to or hammers a limit that has not reset — the server already
knows the answer.
429 is always retryable, and with idempotency-keyed writes a retry can never double-create. The OrderCore SDKs (@ordercore/sdk, ordercore for Python) implement this policy out of the box.
Design agents to batch reads
Catalog reads (search_products, get_prices, get_inventory) dominate agent traffic. Prefer one filtered list call over N item calls, and cache stable catalog data between turns — your rate limit is spent where it earns conversions: on checkout.