Documentation menu

Error format

NFL MCP returns structured errors so an agent can reason about what went wrong. There are two layers: a tool-level error envelope returned inside an otherwise successful response, and transport-level rejections carried by the HTTP status.

Last updated 2026-07-16

Tool-level error envelope

When a tool cannot fulfil a request, it returns a JSON object with a stable machine error code, an agent-readable message, and a retryable boolean. Some errors add hint fields — for example candidates on an ambiguous player. Messages are safe to surface: filesystem paths are stripped and no stack traces are included.

Example — ambiguous_player

{
  "error": "ambiguous_player",
  "message": "'Josh Allen' matches multiple players; pass team or gsis_id to disambiguate.",
  "retryable": false,
  "candidates": [
    {
      "name": "Josh Allen",
      "position": "QB",
      "team": "BUF",
      "gsis_id": "00-0034857"
    },
    {
      "name": "Josh Allen",
      "position": "LB",
      "team": "JAX",
      "gsis_id": "00-0035250"
    }
  ]
}

Error codes

error is drawn from this closed set. Only timeout is retryable by default; transient operational states may also set retryable: true.

Code	Retryable	Meaning
`data_unavailable`	no	The requested dataset or connection is unavailable (also used for transient ingest/deploy skew, which is marked retryable).
`invalid_sql`	no	A raw query was malformed — a bind, parse, or type error.
`timeout`	yes	The query exceeded its time budget. Retrying may succeed.
`row_cap_exceeded`	no	The result exceeded the row cap. Narrow the query.
`ambiguous_player`	no	A player name matched more than one player. Retry with a team or gsis_id from candidates.
`invalid_param`	no	A parameter was missing or invalid.
`forbidden`	no	The tool requires a higher tier than the account holds.

Transport-level rejections

Authentication and quota failures are rejected before a tool runs and are carried by the HTTP status with a { error: { code, message } } body — a different shape from the tool-level envelope above. 401 means an invalid or revoked key; 429 means the daily quota is exhausted (see Rate limits & quotas).

HTTP 401 — invalid_key

{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or revoked API key."
  }
}