Reference
Rate limits
Limits protect the API from floods, not from normal resellers. Each account has one limit per minute that grows with its spend, and a few narrow limits cover heavy actions. Rules that belong to one order, such as the refill wait, return their own error code instead of a 429.
Rate-limit layers
Per-IP
20,000 requests / minute / IP address
Applied before key validation so brute-force key enumeration is bounded. Shared across all keys behind the same IP. The default is set globally and is not user-configurable.
Shared account window
120–2,400 requests / rolling 60 seconds
All active API keys on one account consume the same counter. The fixed lifetime-successful-spend ladder supplies the limit unless a direct admin RPM override exists.
Action-specific
Depends on the action
Services, catalog, cancel, refill and the webhook actions have their own narrow limits, shown below. They add to the account limit; they do not replace it.
Per-action limits
These limits count per account per minute. A 429 from one of them reports action in X-RateLimit-DeniedBy. Cancel and refill count order ids, not requests, so one call for 10 orders uses 10 of the ids you have per minute. A cancel or refill with more ids than that, up to 100, goes through when it is your first of the minute and uses the whole minute.
| Action | Per minute | What is counted |
|---|---|---|
| services | 10 | Requests |
| catalog | 30 | Requests |
| cancel | 30 | Order ids |
| refill | 30 | Order ids |
| webhook.* | 10 | Requests |
Lifetime successful-spend ladder
Your account limit follows your lifetime successful spend; a higher tier unlocks a higher limit at once. The IP ceiling of 20,000 requests a minute applies before the key is checked. An admin can set a direct limit for an account, up to 10,000. The tier your account has is in the X-RateLimit-Tier header and on your API page.
| Tier | Minimum lifetime spend | Requests / minute |
|---|---|---|
| 0 | $0 | 120 |
| 1 | $10 | 300 |
| 2 | $50 | 600 |
| 3 | $100 | 900 |
| 4 | $500 | 1,200 |
| 5 | $1,000 | 1,800 |
| 6 | $2,500 | 2,400 |
Response headers
Response headers
X-RateLimit-Limit- On normal responses, the effective shared account requests-per-minute limit. On a 429, the limit reported by the rejecting layer.
X-RateLimit-Remaining- On normal responses, requests remaining in the shared account window. On a 429, the remaining value reported by the rejecting layer.
X-RateLimit-Reset- Relative number of seconds until the reported window resets; it is not a Unix timestamp.
X-RateLimit-Tier- The earned lifetime-successful-spend tier (0–6). A custom RPM override does not change this value.
X-RateLimit-DeniedBy- Sent on 429 responses when a named limiter rejects the call: "ip", "api_requests_per_minute", or "action".
Retry-After- On a retryable 429 or 503 with Retry-After, wait at least this many seconds before retrying. For action=add, reuse the same idempotency key after the wait.
Handling 429 responses
Wait for Retry-After when it is present.
Otherwise wait for X-RateLimit-Reset seconds. Both values are relative delays, not clock times; add jitter before retrying.Read X-RateLimit-DeniedBy.
It names the limit that rejected the call. Changing keys does not help, because the account, IP and action limits are shared.Use webhooks instead of polling.
Webhooks arrive at least once, so keep your handler idempotent and useaction=statusto check anything important.Batch where you can.
Status, cancel and refill take up to 100 ids in one request; counts of order ids still apply to cancel and refill.