Help
Rate limits
Limits protect the service for every shop. They are counted per calling server (by its IP address) and reset on a rolling window.
Current limits
| What | Limit |
|---|---|
| All API requests | 120 per minute |
| Creating calls: quotes, quote options, bookings, cancellations, payment intents and labels (counted together) | 60 per hour |
| Store orders and ship runs | 60 per hour |
| Webhook endpoint changes (create, disable, test) | 30 per hour |
| Ship runs in progress at once | 5 per Business |
| Checkout sessions and selection checks (per secret key) | 600 per minute |
| Checkout widget calls from browsers (per publishable key) | 300 per minute by default, set per key (10–6000) |
| Prices per checkout session | 40 |
Headers
Responses carry the IETF RateLimit and RateLimit-Policy headers, one entry per limit that applies (r = requests left, t = seconds until the window resets). A 429 also has Retry-After in seconds, and its body is plain text, not the JSON error envelope.
HTTP/1.1 429 Too Many Requests
RateLimit: "120-in-1min"; r=97; t=41, "60-in-1hr"; r=0; t=1312
RateLimit-Policy: "120-in-1min"; q=120; w=60; pk=:…:, "60-in-1hr"; q=60; w=3600; pk=:…:
Retry-After: 1312
Content-Type: text/html; charset=utf-8
Too many requests, please try again later.Handling 429
- Wait for
Retry-After, then retry with the same idempotency key. - The SDK waits automatically when the wait is short (up to 20 seconds by default) and otherwise throws
QoeneRateLimitErrorwithretryAfterSeconds, so you can queue the work. - Spread background jobs (for example tracking refreshes) over time, and prefer webhooks to polling.