Understand ALT Sports Data HTTP status codes, error payloads, and recovery patterns.

Error Handling

ALT Sports Data uses standard HTTP status codes and consistent error payloads so applications can recover cleanly.

Common status codes

Code	Status	Description
200	OK	Request succeeded
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	API key does not have access
404	Not Found	Requested resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error
503	Service Unavailable	Temporary disruption

Error payload shape

Most failed requests return an error object:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "Additional context"
    }
  }
}

Common failure cases

Invalid API key

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked"
  }
}

Validation error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "limit": "Must be between 1 and 100"
    }
  }
}

Rate limit error

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please retry after 1678886400",
    "retry_after": 1678886400
  }
}

Recovery guidance

async function fetchJson(url, headers) {
  const response = await fetch(url, { headers });

  if (response.ok) {
    return response.json();
  }

  const errorPayload = await response.json();
  throw new Error(
    `${response.status}: ${errorPayload.error?.message ?? 'Request failed'}`
  );
}

import requests

def fetch_json(url: str, headers: dict[str, str]):
    response = requests.get(url, headers=headers)

    if response.ok:
        return response.json()

    payload = response.json()
    message = payload.get('error', {}).get('message', 'Request failed')
    raise RuntimeError(f'{response.status_code}: {message}')

Error Handling

On this page