01API
API v1For developers
Rate limits
Every response carries where the key stands in its current one-minute window:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Calls allowed in the window |
X-RateLimit-Remaining | Calls left |
X-RateLimit-Reset | When the window ends, in seconds since 1970 |
Retry-After | Only on a 429: seconds to wait |
A call over the limit is 429 rate_limited. Wait Retry-After seconds and send it again (with the same Idempotency-Key if it was a write).
The limits
| Key | Limit |
|---|---|
| Public catalog key | 120 calls a minute |
| FFL Checkout key | 120 calls a minute |
| Scoped private key | 600 calls a minute, all routes together. Within that: 120 a minute for writes to orders, 300 a minute for inventory writes, 60 a minute for inventory batches. A batch is one call however many items it holds. |
| Private catalog key made before permissions | Counted and reported in the headers at 600 a minute; not enforced yet. When it will be is announced first, with the six months' notice, in the changelog. |
Limits are counted in each server that answers, so across several servers the effective limit can be somewhat higher; do not rely on that. If you need more, ask: the numbers are published and changes are announced.
Be kind
- Use
updated_sinceand cursors instead of re-reading everything. See Pagination. - Use webhooks instead of polling for "did it ship". See Webhooks.
- Use the batch for inventory instead of one call per item. See the inventory guide.
- Back off on
429and503; do not retry in a tight loop.