SportriX API Error Codes and JSON Response Format

When a request cannot be completed, SportriX 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

{ "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 for the full scope-to-endpoint mapping.

404 Not Found

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.

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.

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.

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.

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

Handling errors in your code

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.

A minimal error-handling pattern in Python:

import requests

response = requests.get(
    "https://api.sportrix.ai/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()

Get Started

Core Concepts

Guides

SportriX API Error Codes and JSON Response Format

Error response format

Error codes

Notes on specific codes

401 Unauthorized

403 Forbidden

404 Not Found

422 Unprocessable Entity

Handling errors in your code

​Error response format

​Error codes

​Notes on specific codes

​401 Unauthorized

​403 Forbidden

​404 Not Found

​422 Unprocessable Entity

​Handling errors in your code

Error response format

Error codes

Notes on specific codes

401 Unauthorized

403 Forbidden

404 Not Found

422 Unprocessable Entity

Handling errors in your code