Rate Limits
Per-integration budgets with a shop-wide ceiling; standard RateLimit-* headers; 429 with Retry-After.
Limits protect the shop floor: a runaway script must never slow down the people using Shop Commander. They are keyed on the integration, not the key, and every shop has an aggregate ceiling.
| Layer | Default |
|---|---|
| Per integration, sustained | 300 requests / minute |
| Per integration, burst | 60 requests / 10 seconds |
| Per integration, writes | 60 writes / minute |
| Per shop, all integrations | 1,000 requests / minute |
Every response carries the current state:
RateLimit-Limit: 300
RateLimit-Remaining: 287
RateLimit-Reset: 41
When a budget is exhausted the API answers 429 rate_limited with Retry-After (seconds) and details.retry_after_seconds. Back off for that long, then continue; do not hammer.
Staying inside the limits
- Use
updated_aftercrawls and webhooks instead of polling whole collections. - Ask for
limit=200on bulk reads. - Batch your own work: one integration syncing every minute needs a few requests, not hundreds.
- Cache
GET /v1/shopconservatively and refresh it periodically; V1 does not publish a shop-profile change event.
Higher limits
Platform operators can assign a higher profile to an integration with a demonstrated need (a large fleet, a busy booking site). Ask the shop to contact support with the integration's name and expected volume.
Degraded mode
If the shared limiter is briefly unavailable the API keeps serving on a conservative local budget (about half the advertised numbers per server). You may see earlier 429s for a few minutes; the headers stay accurate.