title: Rate Limiting

description: Understand and work within Wontopos API rate limits.

Rate Limiting

Rate limits protect API stability and ensure fair usage. When you exceed a limit, the API returns 429 Too Many Requests.

Rate limit headers

Every response includes rate limit information:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait before retrying (on 429 only)

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1711705260

Limits by plan

Plan	Requests / minute	Requests / day	Burst limit
Free	60	1,000	10
Pro	1,000	100,000	100
Enterprise	Custom	Unlimited	Custom

Endpoint-specific limits

Some endpoints have stricter limits. See the [Rate Limits reference](/docs/reference/rate-limits) for per-endpoint details.

Handling 429 responses

When you receive a 429 status, read the Retry-After header and wait before retrying:

async function callWithRateLimit(fn: () => Promise<any>) {
  try {
    return await fn();
  } catch (err) {
    if (err instanceof RateLimitError) {
      const delay = err.retryAfter || 60;
      console.log(`Rate limited. Retrying in ${delay}s...`);
      await new Promise(r => setTimeout(r, delay * 1000));
      return await fn();
    }
    throw err;
  }
}

Backoff strategy

For repeated 429s, use exponential backoff with jitter:

Initial wait

Use the `Retry-After` header value, or default to 1 second.

Exponential increase

Double the wait time on each subsequent retry: 1s, 2s, 4s, 8s.

Add jitter

Add random jitter (0-500ms) to avoid thundering herd.

Cap and stop

Cap maximum wait at 60 seconds. Stop after 5 retries.