Quotas, rate limits and errors
Limits
| Limit | Development tier¹ | Approved application | Counted per |
|---|---|---|---|
| Burst | 30 calls / minute | 60 calls / minute | manager, shared across tokens |
| 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 |
| Other matches looked into | 500 / day | 500 / day | manager, across every tool |
| Other clubs scouted | 40 / day, 200 / 30 days | same | manager, across every tool |
| Other matches' shooting read | 100 / day, 500 / 30 days | same | manager, across every tool |
| Other clubs / players / matches | 4,000 / 15,000 / 5,000 per day | same | application, across all its managers |
| Other clubs scouted | 300 / day, 2,000 / 30 days | same | application, across all its managers |
| Other matches' shooting read | 1,000 / day, 5,000 / 30 days | same | application, across all its managers |
| 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.
Daily counters reset at 00:00 UTC. The advanced 30-day limits use rolling windows: switching dates, tokens or managers within an application does not reset them. Own clubs and their matches do not consume foreign-resource breadth; all calls still consume the call quota. Supporter status increases the call quota only, never the breadth limits. Re-reading an admitted resource costs no additional distinct-resource slot. An id refused at the cap remains refused on retry.
Public API exports return 503 PublicApiQuotaUnavailable while shared counters are unavailable;
limits are never silently bypassed during an outage. Ordinary game reads are unaffected.
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 or shared export counters are unavailable; try again shortly | Retry, PublicApiQuotaUnavailable |
| 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 RateLimitedand503: wait (Retry-Afterwhen given, otherwise a few seconds with backoff) and retry.429 PublicApiQuotaExceeded: stop untilX-RateLimit-Reset.429 PublicApiBreadthExceeded: stop new foreign-resource reads; daily limits reset atX-RateLimit-Reset, while rolling advanced limits recover as old resources leave their 30-day window. Previously admitted resources can still be read within the other budgets.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,403or404unchanged.
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.