Errors

Use this page to understand an error response and fix the request that caused it.

Fastest way: ask your AI. Error messages say what’s wrong, and for a misspelled parameter they name the right one. Set up your coding tool once with Build with AI, then paste the request and the full error:

This TheStatsAPI request failed. Check it against https://api.thestatsapi.com/llms.txt and fix it. Request: <paste URL>. Error: <paste JSON>

The error format

Every error has the same shape. The HTTP status code is repeated in the body.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Match not found",
    "status_code": 404
  }
}

Field	Meaning
`code`	An UPPERCASE code. Use this in your logic.
`message`	What went wrong, in plain English. Log it and show it to your AI tool.
`status_code`	The HTTP status, such as `404`.

Error codes

Status	Code	When it happens	What to do
400	`BAD_REQUEST`	A parameter is missing or invalid. For example `season_id is required`, `Invalid match_id` or `per_page cannot exceed 100`.	Fix the parameter named in `message`.
400	`UNKNOWN_PARAMETER`	You sent a query parameter the endpoint doesn’t accept, such as `date` instead of `date_from`.	Use the name the message suggests. The message also lists every parameter the endpoint accepts.
400	`SEASON_COMPETITION_MISMATCH`	`season_id` belongs to a different competition from `competition_id`.	Get the right season from `GET /football/competitions/{competition_id}/seasons`.
400	`PAGE_OUT_OF_RANGE`	`page` is past the last page on `/football/matches`.	Stop at `meta.total_pages`. See Pagination.
401	`UNAUTHORIZED`	The `Authorization` header is missing, isn’t in `Bearer` format, or the key is invalid.	Send `Authorization: Bearer YOUR_API_KEY`. Copy your key from API keys.
403	`FORBIDDEN`	The key is inactive or expired, or the account is inactive.	Check the key and your account on the dashboard.
403	`KEY_REVOKED`	The key has no active plan.	Choose a plan on the pricing page.
403	`ADDON_REQUIRED`	The endpoint needs an add-on your plan doesn’t include.	See the pricing page.
404	`NOT_FOUND`	The ID doesn’t exist, the path is wrong (`Route not found`), or the data doesn’t exist, such as `Heatmap not available for this player in this match`.	Check the ID and path. Check availability flags before calling optional endpoints.
404	`STATS_NOT_AVAILABLE_AT_SOURCE`	Detailed stats were never collected for this finished match.	Don’t retry. This won’t change for that match.
405	`METHOD_NOT_ALLOWED`	You used a method other than `GET`. The API is read-only.	Use `GET`.
409	`CONFLICT`	You called a live endpoint for a match that isn’t live (`Match is not live`), or a post-match endpoint while the match is live.	Check the match `status`. Use the live endpoints during the match and the regular ones after it.
409	`MATCH_IS_LIVE`	You asked for full match stats while the match is still being played.	Use `/football/matches/{match_id}/live-stats` until full time.
429	`RATE_LIMITED`	You used up your per-minute limit.	Wait for the number of seconds in the `Retry-After` header, then retry. See Rate limits.
429	`USAGE_LIMIT_EXCEEDED`	You used up your monthly quota.	Don’t retry. The quota resets when your billing cycle rolls over, or you can upgrade your plan.
500	`INTERNAL_SERVER_ERROR`	Something went wrong on our side.	Retry after a short wait.

Examples

400 UNKNOWN_PARAMETER: a misspelled or unsupported parameter

There is no date parameter on /football/matches, so this request fails:

curl "https://api.thestatsapi.com/api/football/matches?team_id=tm_9145&date=2026-10-10" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "error": {
    "code": "UNKNOWN_PARAMETER",
    "message": "Unknown query parameter 'date' (did you mean 'date_from' or 'date_to'?). Supported parameters: page, per_page, limit, competition_id, season_id, team_id, date_from, date_to, utc_offset, matchday, status, stage, group, sort.",
    "status_code": 400
  }
}

The fix: ?team_id=tm_9145&date_from=2026-10-10&date_to=2026-10-10.

400 SEASON_COMPETITION_MISMATCH: a season from another competition

{
  "error": {
    "code": "SEASON_COMPETITION_MISMATCH",
    "message": "season_id does not belong to competition_id",
    "status_code": 400
  }
}

401 UNAUTHORIZED: missing or invalid key

No Authorization header:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing authorization header",
    "status_code": 401
  }
}

Other messages you may see: Invalid authorization format. Use: Bearer <api_key> (the key was sent without Bearer ) and Invalid API key.

403 KEY_REVOKED: no active plan

{
  "error": {
    "code": "KEY_REVOKED",
    "message": "API key has no active subscription plan",
    "status_code": 403
  }
}

404 NOT_FOUND: the ID doesn't exist

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Match not found",
    "status_code": 404
  }
}

A misspelled path, such as /football/matchez, returns the same code with the message Route not found.

409 CONFLICT: live endpoint for a match that isn't live

Calling /football/matches/{match_id}/live-stats for a finished match:

{
  "error": {
    "code": "CONFLICT",
    "message": "Match is not live",
    "status_code": 409
  }
}

429 RATE_LIMITED: too many requests this minute

The response includes a Retry-After header with the seconds to wait.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please slow down your requests.",
    "status_code": 429
  }
}

Handle errors in code

Check code, not just the HTTP status. Two errors can share a status but need different handling, such as RATE_LIMITED and USAGE_LIMIT_EXCEEDED.

const BASE_URL = "https://api.thestatsapi.com/api";
const headers = { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` };

class TheStatsApiError extends Error {
  constructor(status, code, message) {
    super(`${status} ${code}: ${message}`);
    this.status = status;
    this.code = code;
  }
}

async function getJson(path) {
  const res = await fetch(`${BASE_URL}${path}`, { headers });
  const body = await res.json().catch(() => null);

  if (!res.ok) {
    const { code = "ERROR", message = res.statusText } = body?.error ?? {};
    throw new TheStatsApiError(res.status, code, message);
  }
  return body;
}

// Returns null when the match doesn't exist, and rethrows anything else.
async function getMatch(matchId) {
  try {
    const { data } = await getJson(`/football/matches/${matchId}`);
    return data;
  } catch (err) {
    if (err.code === "NOT_FOUND") return null;
    throw err;
  }
}

console.log(await getMatch("mt_200199332"));

import os
import requests

BASE_URL = "https://api.thestatsapi.com/api"
HEADERS = {"Authorization": f"Bearer {os.environ['THESTATSAPI_API_KEY']}"}

class TheStatsApiError(Exception):
    def __init__(self, status, code, message):
        super().__init__(f"{status} {code}: {message}")
        self.status = status
        self.code = code

def get_json(path, params=None):
    res = requests.get(f"{BASE_URL}{path}", headers=HEADERS, params=params)
    if not res.ok:
        try:
            error = res.json()["error"]
        except (ValueError, KeyError):
            error = {"code": "ERROR", "message": res.reason}
        raise TheStatsApiError(res.status_code, error["code"], error["message"])
    return res.json()

# Returns None when the match doesn't exist, and re-raises anything else.
def get_match(match_id):
    try:
        return get_json(f"/football/matches/{match_id}")["data"]
    except TheStatsApiError as err:
        if err.code == "NOT_FOUND":
            return None
        raise

print(get_match("mt_200199332"))

For 429 responses, wait and retry as shown in Rate limits.

Get started

Guides

Core concepts

The error format

Error codes

Examples

Handle errors in code

​The error format

​Error codes

​Examples

​Handle errors in code

The error format

Error codes

Examples

Handle errors in code