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 waiting to run. | 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 completed Gameweek, Gameweek in progress, or Gameweek not complete | Wait until Fantasy Premier League finalises the scores. |
RATE_LIMITED |
Stop retrying and try again later. Existing published editions can still be read. |
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, stop after completed or failed, and do not create parallel jobs while one is queued or processing.