Getting started

Rate limits

Requests are rate limited per API key, on a tiered basis. Every response tells you exactly where you stand.

Two budgets per key

Each key carries two independent budgets: replay covers the replay-parser endpoints (every request uploads tens of megabytes, so it stays tight) and api covers everything under /guilds/:guildId — lightweight JSON, so it's far more generous. Heavy replay parsing never eats your integration's API budget, and vice versa.

Tiers

Tier	Budget	Per minute	Per day
Free	`replay`	`5`	`50`
	`api`	`120`	`20,000`
Pro	`replay`	`60`	`2,000`
	`api`	`600`	`200,000`

Guild-scoped keys created on the dashboard are minted at the Pro tier — 600 requests/minute and 200,000/day against the Guild API. All guild endpoints (including webhook management) share the api budget; the replay parser uses the replay budget.

Response headers

Every response includes the rate-limit state of the budget that endpoint uses:

Header	Description
`X-RateLimit-Limit`	Your ceiling for the current window.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp (seconds) when the window resets.
`Retry-After`	Seconds to wait before retrying. Sent only on a `429` response.

When you exceed a limit

Once you go over your limit the API responds with 429 Too Many Requests, a Retry-After header, and this JSON body:

json

{
  "error": "rate_limited",
  "retryAfter": 42
}

Back off and retry

Wait at least retryAfter seconds (or until X-RateLimit-Reset) before sending another request. See the Errors page for the full status-code list.

Check your tier and usage

Call the key endpoint to see your tier and today's usage in both budgets without spending a request that counts:

GET/key

bash

curl https://api.zyron.pro/api/v1/key \
  -H "Authorization: Bearer zyr_xxxxxxxxxxxxxxxxxxxxxxxx"

json

{
  "tier": "pro",
  "limits": {
    "perMinute": 60,
    "perDay": 2000,
    "replay": { "perMinute": 60, "perDay": 2000 },
    "api": { "perMinute": 600, "perDay": 200000 }
  },
  "usage": {
    "day": "2026-07-10",
    "dayCount": 12,
    "replay": 12,
    "api": 481
  }
}

The top-level perMinute/perDay and dayCount fields mirror the replay budget for backwards compatibility.