Buckets
The app has its own bucket, and the store has one for all its apps together. A request takes a token from both; reads and writes share them.
| Bucket | Requests per minute | In a row |
|---|---|---|
| Each app | 300 | 100 |
| The store, all apps together | 1200 | 400 |
"In a row" is how many requests pass without a pause; after that, the bucket refills at the rate per minute.
Headers
Every response reports both buckets, by the IETF draft of RateLimit headers: RateLimit-Policy names each bucket with its quota per window, q and w in seconds; RateLimit tells how many requests are left in a row, r, and in how many seconds the bucket is full again, t. Slow down by r instead of waiting for an error.
On 429
A request over the limit gets 429 too_many_requests: policy names the bucket that ran out and Retry-After how many seconds to wait. A rejected request takes no token from the other bucket.
curl "https://api.saleya.app/v1/products?limit=250" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"HTTP/1.1 429 Too Many Requests
Retry-After: 1
RateLimit-Policy: "app";q=300;w=60, "store";q=1200;w=60
RateLimit: "app";r=0;t=20, "store";r=310;t=5
{
"type": "too_many_requests",
"title": "Too many requests",
"status": 429,
"detail": "The app rate limit is exhausted. Retry after the number of seconds in the Retry-After header.",
"policy": "app"
}Requests rejected on entry — a 401, or a 403 for an address that is not allowed or a plan without the API — are counted per address, apart from the buckets. After 60 of them in a minute, the address gets 429 with policy set to rejected until the minute ends. Requests with a valid token are not counted. Fix the cause the 401 or 403 named instead of repeating the request.
Fewer requests
- Thousands of records: one bulk operation instead of a request per record.
- Changes: webhooks and the sync cursor instead of polling lists.
- Pages of up to 250 records instead of the default size.
- Several integrations of one store share the bucket of the store: spread heavy jobs in time.
Other ceilings and retention periods of the API are in the table of limits.