Developers · BuzzerBeater

Quotas, rate limits and errors

Limits

Limit	Development tier¹	Approved application	Counted per
Burst	30 calls / minute	60 calls / minute	token
Daily quota	1,500 calls	5,000 calls	manager × application
Supporter managers	daily quota × 2	daily quota × 2
Other clubs looked into	400 / day	400 / day	manager, across every tool
Other players looked up	1,500 / day	1,500 / day	manager, across every tool
Listed players' skills revealed	20 / day, 150 / 30 days	same	manager
Listed players' skills revealed	300 / day, 2,000 / 30 days	same	application, across all its users
Transfer list search depth	150 players (pages of up to 30)	same	search
Token endpoint	20 requests / minute	same	address

¹ Personal tokens, and applications not approved yet.

Days are UTC days: every counter resets at 00:00 UTC. Staff may give an approved application a different daily quota when it needs one — ask in its review.

Each data response tells you where you stand:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9731
X-RateLimit-Reset: 1790640000

X-RateLimit-Reset is the Unix time the daily quota resets. When the burst limit is hit the answer is 429 with a Retry-After header in seconds.

Errors

Every error of a data call is JSON with a stable code to branch on and a description for humans:

{ "error": { "code": "PublicApiQuotaExceeded", "description": "The daily call quota for this manager and application is used up. It resets at midnight UTC." } }

Status	When	Typical codes
400	The request is malformed or out of range	`InvalidData`, `PublicApiPageInvalid`, `PublicApiSearchTooDeep`, …
401	No token, or it is unknown, expired or revoked	`InvalidToken`
403	The token lacks the scope, or the manager may not see this	`InsufficientScope`, `PublicApiScopeMissing`, `MissingPermission`, `SupporterRequired`
404	The club, player, match … does not exist	`TeamIdInvalid`, `PlayerIdInvalid`, `NotFound`, …
429	A limit was reached	`RateLimited` (burst, see `Retry-After`), `PublicApiQuotaExceeded`, `PublicApiBreadthExceeded`, `PublicApiListedSkillsExceeded`
503	A short conflict inside the game; try again shortly	`Retry`
500	Our fault	`InternalServerError`

Branch on the status first and on code when you need detail. New codes may appear within v1; treat an unknown code like the others of its status.

Retrying

401: refresh the access token once; if that fails, sign the manager in again.
429 RateLimited and 503: wait (Retry-After when given, otherwise a few seconds with backoff) and retry.
429 PublicApiQuotaExceeded / PublicApiBreadthExceeded: stop until X-RateLimit-Reset. Retrying earlier only fails.
429 PublicApiListedSkillsExceeded: the listed-skill caps count over a day and over 30 days; show the auction without skills and let the manager open the player in the game.
Never retry 400, 403 or 404 unchanged.

Staying well within the quota

Cache: seasons, countries and leagues change a few times a season; a finished match never changes; a roster changes at most a few times a day.
Ask for the whole thing once rather than piece by piece: a roster includes its players' public figures, so you rarely need one call per player.
Schedule background refreshes around the game's own updates (training, matches) rather than polling.