API rate limits

Per-key token bucket

Each API key has a token bucket with a burst of 60 tokens and a refill rate of 1 token per second. Reads cost 1 token. Writes cost 2 tokens.

Creating a product update notification (POST /products/{shopify_product_id}/notifications, a dry run included) costs 10 tokens. The notify_customers flag on a mapping write adds nothing: that write costs its usual 2 tokens whether or not it asks for a notification. The 7-day limit of one notification per product is a separate rule with its own code, 429 notification_cooldown: its Retry-After can be up to seven days, so do not retry it automatically — schedule the next call at error.details.next_available_at.

A shop can also have at most 5 product update notifications queued or sending at once. A sixth is 429 too_many_active_notifications, a third kind of 429 next to rate_limited and notification_cooldown, so tell them apart by error.code, not by the status. It has no Retry-After: poll GET /notifications/{id} for one of error.details.active_notification_ids and retry once that campaign has finished.

When the limit is exceeded, the API returns 429 rate_limited.

Rate limit headers

Retry-After: 12
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-06-05T12:00:00.000Z

Wait at least the Retry-After duration before retrying. Reuse the same Idempotency-Key when retrying the same write.

Resend email limit

The order resend endpoint has an additional per-order safety limit of 3 resend requests per hour.