Rate Limits

Rate limits are enforced per API key and reset monthly. Choose a plan that fits your usage.

Limits by Plan

Plan	Requests/Month	Requests/Minute	Burst Limit
Free	500	10	20
One Game Starter	10k-250k	30	60
Basic	50,000	30	60
Pro	250,000	100	200
Business	2,000,000	500	1,000
Enterprise	Unlimited*	Custom	Custom

* Enterprise plans have custom limits based on your needs. Contact sales for details.

Response Headers

Every API response includes rate limit headers to help you track your usage:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1705348800

Header	Description
`X-RateLimit-Limit`	Maximum requests per minute for your plan
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the limit resets

Handling Rate Limits

When you exceed your limit, you'll receive a 429 response:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You hit your current request limit. If you’re polling live data frequently, webhooks can reduce unnecessary requests by pushing updates directly to your app. Upgrade for higher limits or use webhooks for real-time updates.",
    "docs": "https://citoapi.com/docs/rate-limits",
    "actions": [
      {
        "label": "Upgrade plan",
        "url": "https://citoapi.com/dashboard/billing/plans"
      },
      {
        "label": "Learn about webhooks",
        "url": "https://citoapi.com/webhooks/"
      }
    ],
    "upgradeUrl": "https://citoapi.com/dashboard/billing/plans",
    "webhooksUrl": "https://citoapi.com/webhooks/"
  }
}

Respect the retry_after value

Wait the specified number of seconds before retrying. Repeated violations may result in temporary bans.

Best Practices

Cache responses when possible

Store frequently accessed data locally to reduce API calls. Player stats rarely change mid-match.

Use webhooks instead of polling

Subscribe to events rather than polling every few seconds. This reduces your request count dramatically. See live webhook delivery.

Implement exponential backoff

When retrying after errors, wait progressively longer between attempts (1s, 2s, 4s, 8s, etc.).

Monitor your usage

Check your dashboard regularly to see usage patterns and upgrade before hitting limits.

Need higher limits?

Upgrade your plan or contact us for custom enterprise pricing.

View Plans