Error Handling

Error codes and handling are consistent across all 25+ sports APIs and all three API versions (V1, V2, V3).

Error Response Format

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
  }
}

HTTP Status Codes

Status	Description
`200`	Success
`400`	Bad Request — invalid parameters
`401`	Unauthorized — invalid or missing API key
`403`	Forbidden — access denied or account suspended
`404`	Not Found — resource doesn’t exist
`429`	Too Many Requests — daily rate limit exceeded
`500`	Internal Server Error
`503`	Service Unavailable — temporary outage

Common Errors

401 — Missing or Invalid API Key

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Valid x-api-key header or Bearer token required"
  }
}

Fix: Include the x-api-key header in every request:

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.sportsapipro.com/v2/football/live"

429 — Rate Limit Exceeded

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Daily quota exceeded. Resets at midnight UTC."
  }
}

Fix: Wait until reset, implement caching, or upgrade your plan. See Rate Limits.

404 — Resource Not Found

Returned when a match ID, team ID, or tournament ID doesn’t exist for that sport. Fix: Verify the ID is correct and belongs to the sport you’re querying. Use /api/search to find valid IDs.

503 vs 404 on collection routes

On collection routes — live, today, schedule/round, standings and seasons lists — the two status codes mean different things and need different handling:

503 means the upstream data layer temporarily failed to answer. It is always retryable: repeat the same request after a short backoff and it will normally succeed.
404 means the resource genuinely doesn’t exist (for example, a tournament ID that isn’t valid, or a competition with no fixtures that day). Retrying a 404 on these routes is pointless — fix the ID instead.

if (response.status === 503) {
  // transient — retry with backoff
} else if (response.status === 404) {
  // permanent — the collection is genuinely empty or the ID is wrong
}

This applies to item-level endpoints too: a repeated 404 on /api/match/{id}/statistics or /lineups is a real answer (no data recorded for that match), while a 5xx is transient.

Error Handling Examples

const SPORTS = {
  football: 'https://api.sportsapipro.com/v2/football',
  basketball: 'https://api.sportsapipro.com/v2/basketball',
  tennis: 'https://api.sportsapipro.com/v2/tennis',
  baseball: 'https://api.sportsapipro.com/v2/baseball',
};

async function fetchSport(sport, endpoint) {
  const response = await fetch(`${SPORTS[sport]}${endpoint}`, {
    headers: { 'x-api-key': process.env.SPORTSAPI_KEY }
  });
  
  if (!response.ok) {
    const data = await response.json().catch(() => ({}));
    const code = data?.error?.code || response.status;
    const msg = data?.error?.message || response.statusText;
    
    if (response.status === 429) {
      const reset = response.headers.get('X-RateLimit-Reset');
      throw new Error(`Rate limited. Resets at ${reset}`);
    }
    throw new Error(`${sport} API error ${code}: ${msg}`);
  }
  
  return response.json();
}

// Multi-sport with graceful degradation
async function fetchAllSports() {
  const results = {};
  for (const sport of Object.keys(SPORTS)) {
    try {
      results[sport] = await fetchSport(sport, '/api/live');
    } catch (err) {
      console.error(`${sport}: ${err.message}`);
      results[sport] = null;
    }
  }
  return results;
}

import os, requests

API_KEY = os.environ["SPORTSAPI_KEY"]
HEADERS = {"x-api-key": API_KEY}

SPORTS = {
    "football": "https://api.sportsapipro.com/v2/football",
    "basketball": "https://api.sportsapipro.com/v2/basketball",
    "tennis": "https://api.sportsapipro.com/v2/tennis",
    "baseball": "https://api.sportsapipro.com/v2/baseball",
}

def fetch_sport(sport, endpoint):
    url = f"{SPORTS[sport]}{endpoint}"
    response = requests.get(url, headers=HEADERS)

    if response.status_code == 429:
        reset = response.headers.get("X-RateLimit-Reset", "unknown")
        raise Exception(f"Rate limited. Resets at {reset}")

    if not response.ok:
        error = response.json().get("error", {})
        code = error.get("code", response.status_code)
        msg = error.get("message", response.reason)
        raise Exception(f"{sport} API error {code}: {msg}")

    return response.json()

# Multi-sport with graceful degradation
def fetch_all_sports():
    results = {}
    for sport in SPORTS:
        try:
            results[sport] = fetch_sport(sport, "/api/live")
        except Exception as e:
            print(f"{sport}: {e}")
            results[sport] = None
    return results

Retry Strategy

For transient errors (5xx), implement exponential backoff:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      if (response.status >= 500) throw new Error(`Server error ${response.status}`);
      return response;
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(r => setTimeout(r, delay));
    }
  }
}

Getting Help

Contact Support

Get help from our team

Getting Started

Core Concepts

Updates

Error Response Format

HTTP Status Codes

Common Errors

401 — Missing or Invalid API Key

429 — Rate Limit Exceeded

404 — Resource Not Found

503 vs 404 on collection routes

Error Handling Examples

Retry Strategy

Getting Help

Contact Support

​Error Response Format

​HTTP Status Codes

​Common Errors

​401 — Missing or Invalid API Key

​429 — Rate Limit Exceeded

​404 — Resource Not Found

​503 vs 404 on collection routes

​Error Handling Examples

​Retry Strategy

​Getting Help

Contact Support

Error Response Format

HTTP Status Codes

Common Errors

401 — Missing or Invalid API Key

429 — Rate Limit Exceeded

404 — Resource Not Found

503 vs 404 on collection routes

Error Handling Examples

Retry Strategy

Getting Help