Skip to content

Rate limits

Requests are rate-limited by two token buckets, the same ones AI / Agent access uses:

Bucket Capacity Refill
Per shop 120 2 tokens per second
Per API key 60 1 token per second

A call takes its cost from both buckets at once; if either is short, the call is refused and neither is charged.

  • Most calls cost 1 token; reads and writes cost the same.
  • GET /forecast-views/{id}/rows costs 15 tokens per call, whatever its limit: every call recomputes the view and reads stock fresh. A call above 1,000 rows still costs 15, although Logistified reads it in 1,000-row pages. With one key that is four calls in a burst, then one every 15 seconds.

When a bucket is empty, the API returns 429 RATE_LIMITED with a Retry-After header (seconds).

A forecast-view computation runs alone per shop. While one is running, a second one, from REST or from AI / Agent access, gets 429 RATE_LIMITED with error.data.code = SHOP_BUSY and Retry-After: 15. Wait, then send the same request again. Run forecast-view pulls one after another, never in parallel.

A call above 1,000 rows runs its pages one by one: a heavy call that starts between two pages makes the rest of that call answer 429 SHOP_BUSY. Retry the whole call.

  • Use the bulk endpoints. Every purchase-order line-item and lifecycle endpoint takes a list, so adding, updating, confirming, or receiving 40 lines is one token, not 40. Planning works the same way: add up to 500 plan items (200 on a new product plan) or delete up to 500 in one call. A loop over single items is the fastest way to empty the bucket.
  • Don’t parallelise against one shop. The data store is single-threaded per shop; concurrent requests don’t complete faster and burn tokens. Issue calls sequentially.
  • Page efficiently. Use the largest limit the endpoint allows (50 for lists, 250 for plan item pages) and follow the cursor rather than many small pages.
  • Read a whole forecast view in one call. Forecast views are the exception to cursor paging: separately requested pages are computed separately and can shift, so a sync reads each view with limit=4000, one call for a view of up to 4,000 rows, and never stitches calls together. A larger view is split into disjoint product-filtered views. See Syncing forecast views.
  • Back off on 429. Wait the Retry-After interval and retry the same request.