The Marketplacer GraphQL API enforces rate limits to protect platform stability and ensure fair access across all integrations. This article covers the specific limits, how they work, and how to handle them in your integration.
Rate limit tiers
Three independent limits apply to every API request. A request is rejected if any one of the following thresholds is exceeded:
| Limit | Threshold | Window |
|---|---|---|
| Per source IP | 600 requests | 10 seconds |
| Per API key | 750 requests | 10 seconds |
| Per operator (all keys combined) | 1,200 requests | 10 seconds |
These limits are evaluated independently. You can hit the per-key limit before the operator limit, for example if one integration is sending requests at a particularly high rate while others are idle.
Note: These limits are provided for reference and may be adjusted at any time.
How rate limiting works
When a limit is exceeded, the API returns one of the following HTTP status codes:
- 429 Too Many Requests
- 503 Service Unavailable
Both responses may include a Retry-After header indicating how long to wait before retrying. If no Retry-After header is present, wait at least 60 seconds before retrying.
Handling rate limits in your integration
Check for 429 and 503 responses. Not all errors are data errors. Build handling for these status codes specifically.
Respect the Retry-After header. If the header is present, use its value as your wait time. If it's absent, wait at least 60 seconds before retrying.
Use exponential backoff. If you hit limits repeatedly, increase the wait between retries rather than retrying at a fixed interval (for example, 60s > 120s > 240s).
Spread load across API keys where possible. The per-key limit (750/10s) is lower than the operator limit (1,200/10s). Distributing calls across multiple keys gives your integration more headroom before hitting the operator ceiling.
Avoid large bursts. If your integration does bulk operations such as syncing a product catalog, throttle your request rate to stay well under the per-IP and per-key limits rather than sending requests as fast as possible.
Common scenarios
My sync job hits rate limits overnight.
Throttle bulk jobs to approximately 50–60 requests per second to stay under the per-key limit with headroom. Spreading requests across multiple API keys, each scoped appropriately, can also help.
Multiple integrations share the same IP address.
Integrations running from the same server share the 600/10s IP limit. Consider distributing them across different source IPs, or ensure their combined request rate stays under the threshold.
Our seller integration and operator integration are both hitting limits.
Both consume from the operator-level 1,200/10s pool. Coordinate total throughput across all integrations connected to your operator instance.
Further reading
- Retrying API Requests: Guidance on retry strategies and exponential backoff.
- Operator API Overview: Rate limiting reference on the developer portal.