Reference / 04
Result states
| Status | Meaning | Client action |
|---|---|---|
needs_league_selection |
A league name did not resolve to one unambiguous public league. | Ask the user to choose a candidate or provide the exact ID or URL. |
not_generated |
No published edition exists for the requested Gameweek. | Explain the result. Generate only if canGenerate is true and the user asks. |
queued |
The official edition is saved or waiting to run. A full-time request may be waiting for FPL scoring to settle. | Poll the returned job after the suggested delay. |
processing |
The official edition is being prepared. | Continue polling without starting another job. |
completed |
The canonical edition is published. | Present the exact commentary and its links. |
failed |
The job did not complete. | Show the returned message and allow a user-led retry. |
User-actionable errors
Errors are returned with a short code and a human-readable message. A client should prefer the message and avoid inventing recovery steps.
| Error family | What to do |
|---|---|
| Invalid league, request, or job ID | Ask for a public classic-league ID or URL and correct the invalid field. |
| League not found or needs selection | Ask for the exact league URL or let the user choose a returned candidate. |
| No scoring-ready Gameweek, Gameweek in progress, or Gameweek not ready | Wait for full-time and for Fantasy Premier League scoring to settle. |
RATE_LIMITED |
Stop retrying. Wait for Retry-After or retryAfterSeconds, and do not retry before resetAt. Existing published editions can still be read. |
CAPACITY_REACHED |
Shared capacity for new work is full. Wait until resetAt; do not create a parallel job or switch endpoints. Existing editions, league pages, and job polling remain available. |
GENERATION_PAUSED |
Explain that new editions are temporarily unavailable. Do not work around the pause. |
NOT_FOUND for a job |
Stop polling and ask the user to begin again from their league. |
| Upstream or temporary service error | Keep the original message, avoid rapid retries, and direct persistent problems to support. |
Safe polling
Poll only a job ID returned by generate_weekly_commentary. Respect pollAfterSeconds, including the slower interval while FPL scoring is settling. Stop after completed or failed, and do not create parallel jobs while one is queued or processing.
Machine-safe retries
Direct API 429 responses include Retry-After plus retryAfterSeconds and resetAt in the JSON body. Connected MCP tools return the same fields inside their structured error. Page-local league tools preserve them in the returned error object.
For RATE_LIMITED or CAPACITY_REACHED, wait until the advertised retry window. Do not loop, change from the API to MCP, or create another canonical job to work around the limit. Read-only discovery, published commentary, league pages, shares, and status checks remain available while new work is waiting for capacity.