Rate Limits

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.

Application responses carry the current integration-budget 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_after crawls and webhooks instead of polling whole collections.
• Ask for limit=200 on bulk reads.
• Batch your own work: one integration syncing every minute needs a few requests, not hundreds.
• Cache GET /v1/shop conservatively 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.

Owned edge limits

Shop Commander's Nginx edge also enforces a coarse per-IP request/connection limit and the 1 MB body cap. When that owned edge rejects a request it returns the same JSON ErrorEnvelope: 429 edge_rate_limited with Retry-After, or 413 request_too_large. Its coarse IP 429 does not include RateLimit-Limit, RateLimit-Remaining, or RateLimit-Reset, because those headers describe the integration quota, not the IP guardrail.

Owned-edge 502, 503, and 504 failures also use the JSON envelope. A DNS provider, ISP, browser, or other network intermediary outside Shop Commander's control can still return a non-JSON network failure; clients must retain a fallback for an unreadable or absent error body.