---
title: "Result states and errors"
description: "Handle league selection, commentary availability, progress, and failure without guessing."
---

> Fantasy Pundit documentation index
> Discover the complete public contract at https://fantasypundit.lol/docs/llms.txt

# Result states and errors

## 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.