Documentation Index
Fetch the complete documentation index at: /docs/llms.txt
Use this file to discover all available pages before exploring further.
The Stats API returns consistent JSON error objects for failure cases. Learn the error format, status codes, and common coverage behaviors.
{
"error": {
"code": "string",
"message": "string",
"status_code": 400
}
}
| Field | Type | Description |
|---|---|---|
error.code | string | Machine-readable error code. |
error.message | string | Human-readable explanation. |
error.status_code | integer | HTTP status code mirrored in the body. |
| HTTP status | Code | Meaning |
|---|---|---|
400 | invalid_request | Bad request, invalid filter, unknown enum value, or missing required parameter. |
401 | unauthorized | Missing or invalid API key. |
404 | not_found | The requested resource does not exist, or a coverage-specific object is unavailable. |
| Endpoint type | Behavior |
|---|---|
| Lineups | Returns 404 when the official team sheet has not been announced. |
| Match/player heatmaps | Returns 404 when movement coverage is unavailable for the player, match, or season. |
| Timeline | Returns 200 with an empty events array and meta.coverage = "none" when the match exists but no timeline is available. |
| Optional stats and odds | Check availability flags such as xg_available, odds_available, and live_odds_available before requesting related endpoints. |
const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://api.thestatsapi.com/api";
async function fetchCompetitions() {
const response = await fetch(`${BASE_URL}/football/competitions`, {
headers: {
Authorization: `Bearer ${API_KEY}`,
},
});
if (!response.ok) {
const body = await response.json();
const { code, message, status_code } = body.error;
if (status_code === 401) {
console.error("Authentication failed. Check your API key.");
return;
}
console.error(`API error ${status_code} (${code}): ${message}`);
return;
}
return response.json();
}
Bearer prefix in the Authorization header. Sending Authorization: YOUR_API_KEY without Bearer returns 401 unauthorized.competition_id and season_id together. Supplying only one of the pair can return 400 invalid_request.