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

# Sportrix Data API Error Codes and JSON Response Format

> Sportrix Data returns standard HTTP status codes with a JSON body. Learn what each error code means and how to handle auth, permission, and input errors.

When a request cannot be completed, Sportrix Data returns a standard HTTP error status code alongside a JSON body. Every error response contains a `detail` field with a human-readable explanation of what went wrong — checking this field is the fastest way to diagnose a problem.

## Error response format

```json theme={null}
{ "detail": "Missing required scope: live_scores" }
```

The `detail` string is always present on error responses and is safe to log or surface to developers during debugging.

## Error codes

| Status                     | Meaning                                                                     |
| -------------------------- | --------------------------------------------------------------------------- |
| `401 Unauthorized`         | Missing, unknown, disabled, or expired API key                              |
| `403 Forbidden`            | Your key lacks the required scope for this endpoint                         |
| `404 Not Found`            | Resource doesn't exist, is outside your sport allowlist, or has no data yet |
| `422 Unprocessable Entity` | A required query parameter is missing or malformed                          |

## Notes on specific codes

### 401 Unauthorized

Returned whenever the API cannot authenticate your request. This includes: no `X-API-Key` header present, a key that does not exist, a key that has been disabled by an administrator, or a key that has passed its `expires_at` date.

### 403 Forbidden

Returned when your key is valid but your account has not been granted the scope required by the endpoint you called. For example, calling `GET /matches/{id}/live` without `live_scores` or `live_scores_statistics` returns `403`. See [Scopes and Permissions](/concepts/scopes) for the full scope-to-endpoint mapping.

### 404 Not Found

<Note>
  Requesting a match whose sport is **not in your enabled-sports allowlist** returns `404`, not `403`. This is by design — the API treats out-of-allowlist resources as non-existent rather than forbidden, so your error-handling code does not need to distinguish between the two cases.
</Note>

A `404` can mean any of the following:

* The resource (match, live snapshot, result) genuinely does not exist.
* The match belongs to a sport outside your allowlist.
* No data is available yet — for example, calling `GET /matches/{id}/live` before a match has gone live, or `GET /matches/{id}/result` before any snapshots have been captured.

<Note>
  List endpoints (`GET /leagues`, `GET /matches`) return an **empty `items` array** — not `404` — when a valid query matches zero records. A `404` from a list endpoint would be unexpected.
</Note>

### 422 Unprocessable Entity

Returned when a required query parameter is absent or its value cannot be parsed. For example, omitting the required `sport` parameter on `GET /leagues`, or passing a non-integer where an integer is expected.

<Tip>
  Always read the `detail` field — it will name the specific parameter that is missing or invalid, which makes fixing the request straightforward.
</Tip>

## Handling errors in your code

<Warning>
  Do not rely on the HTTP status code alone. Always check `detail` before logging or rethrowing an error — it contains the context you need to diagnose the issue quickly.
</Warning>

A minimal error-handling pattern in Python:

```python theme={null}
import requests

response = requests.get(
    "https://api.sportrixdata.com/api/matches/41282/live",
    headers={"X-API-Key": "sk_your_api_key_here"},
)

if not response.ok:
    error = response.json()
    print(f"Error {response.status_code}: {error['detail']}")
else:
    data = response.json()
```