Rate limits

The default limit is 120 requests per minute per API key. API Gateway also applies a separate global burst limit to protect platform availability.

When a key exceeds its limit, the API returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded. Retry after the next minute.",
  "retryAfter": 60,
  "requestId": "req_01abc"
}

Retry strategy

Honor Retry-After when present. Otherwise use exponential backoff with jitter:

const delayMs = Math.min(30_000, 500 * 2 ** attempt) + Math.random() * 250;
await new Promise((resolve) => setTimeout(resolve, delayMs));

Retry 429, 408, and 5xx responses. Do not automatically retry other 4xx responses without correcting the request.

Reduce request volume

• Use the maximum practical page size, up to 250.
• Store updatedAt and use updatedSince for incremental item synchronization.
• Use webhooks as change notifications instead of polling continuously.
• Cache material types and locations, which change less frequently than items.