Rate limits

Requests are limited by two token buckets at once: one of the app and one of the store. Every response tells how much is left, so an integration can slow down before it is rejected.

Loading the search index…

Rate limits

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.

Scale
BucketRequests per minuteIn a row
Each app300100
The store, all apps together1200400

"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.

Request
curl "https://api.saleya.app/v1/products?limit=250" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Response
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.

Next guideAPI versioning