Rate limits

Overview

The API uses token bucket rate limiting. Limits are tracked per authenticated API token.

Standard Endpoints

Limit	Window	Tracked by
500 requests	Per minute	API token

Rate Limit Headers

Every response includes rate limit headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per window (500)
`X-RateLimit-Remaining`	Requests remaining in current window
`Retry-After`	Seconds until the window resets (only on 429 responses)

HTTP 429 Response

When the rate limit is exceeded, the API returns:

{
  "message": "Too Many Attempts."
}

Batch Endpoints

Batch endpoints use weighted rate limiting where each item in the batch consumes one unit from the same 500/minute budget.

Endpoint	Method	Array key	Max batch size
`/api/v2/products/batch`	POST	`products`	50
`/api/v2/products/batch`	PUT	`products`	50
`/api/v2/product-variants/batch`	POST	`variants`	50
`/api/v2/variants/batch`	PUT	`variants`	50

How Batch Costs Work

A batch request costs 1 unit per item in the request body array. For example, a POST /api/v2/products/batch with 25 products consumes 25 units from the 500/minute budget.

A request with 1 item = 1 unit

A request with 50 items = 50 units

A request with >50 items is rejected with 422 Unprocessable Entity before any rate limit is consumed

Rate Limit Exceeded During Batch (429)

If the remaining budget is insufficient for the batch size, the entire request is rejected. For example, if 480 units have been consumed and a batch of 25 items is sent, the request is rejected because 480 + 25 > 500.

Best Practices

Monitor rate limit headers — check X-RateLimit-Remaining to avoid hitting limits

Use batch endpoints for bulk operations instead of individual requests

Implement exponential backoff when receiving 429 responses

Overview#

Standard Endpoints#

Rate Limit Headers#

HTTP 429 Response#

Batch Endpoints#

How Batch Costs Work#

Rate Limit Exceeded During Batch (429)#

Best Practices#