> ## Documentation Index
> Fetch the complete documentation index at: https://www.thestatsapi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API error responses and status codes

> The Stats API returns consistent JSON error objects for failure cases. Learn the error format, status codes, and common coverage behaviors.

The Stats API returns structured JSON error objects for failure cases. Your integration should parse the response body instead of assuming an HTML page or empty body.

## Error format

```json theme={null}
{
  "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. |

## Error codes

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

## Coverage behavior

Some endpoints use endpoint-specific behavior when optional coverage 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. |

## Handling errors in code

```javascript theme={null}
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();
}
```

<Warning>
  Always include the `Bearer` prefix in the `Authorization` header. Sending `Authorization: YOUR_API_KEY` without `Bearer ` returns `401 unauthorized`.
</Warning>

<Note>
  Some endpoints require `competition_id` and `season_id` together. Supplying only one of the pair can return `400 invalid_request`.
</Note>