TS
Tournament Suite
TS
Tournament Suite
Developer Documentation
Get StartedPaginationResponse CodesRate LimitsWebhooks
Overview

Rate Limits

How API rate limits work on TournamentSuite and how to stay within them.

API rate limits are tied to your project's plan tier. Limits apply independently to read traffic and write traffic, so a heavy export job does not starve registration or scoring updates. Your current limits and live usage are visible in the Platform developer dashboard under Settings → Developer.

Rate limit headers

Every API response includes headers that tell you where you stand:

HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the current window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp when the window resets

When you exceed your limit, the API responds with 429 Too Many Requests. Retry after the time indicated by X-RateLimit-Reset.

Handling rate limits

async function fetchWithRetry(url: string, headers: Record<string, string>) {
  const response = await fetch(url, { headers });

  if

Staying within limits

  • Cache read responses. Tournament structures, brackets, and participant lists change infrequently between updates. A short TTL cache (30–60 seconds) dramatically reduces read volume.
  • Use webhooks instead of polling. Subscribe to events rather than repeatedly calling the same endpoint to detect changes. See Webhooks.
  • Batch writes where possible. Some endpoints accept arrays; use them instead of making one request per item.

Sandbox limits

Every project includes a sandbox environment with its own separate rate-limit budget. Sandbox traffic never counts against production limits. Use it freely for development, testing, and load testing without affecting live tournaments.

Need higher limits?

For programs with unusual traffic patterns — large registration windows, broadcast-day bursts, or partner integrations with large user bases — contact us to discuss a custom Enterprise rate-limit profile.

Response Codes

HTTP status codes returned by the TournamentSuite API and how to handle them.

Webhooks

Register endpoints to receive real-time event notifications from TournamentSuite.

On this page

Rate limit headersHandling rate limitsStaying within limitsSandbox limitsNeed higher limits?
(response.status
===
429
) {
const resetAt = Number(response.headers.get('X-RateLimit-Reset'));
const waitMs = resetAt * 1000 - Date.now();
await new Promise(resolve => setTimeout(resolve, waitMs + 100));
return fetchWithRetry(url, headers); // retry once
}
return response;
}