Error Handling

Understanding and handling API errors

This documentation applies to all SportsAPI Pro endpoints across all 20+ sports. Error codes and handling are consistent across all APIs.

Error Response Format

All error responses follow a consistent 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
404	Not Found - Resource doesn’t exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error
503	Service Unavailable

Common Errors

Authentication Errors

MISSING_API_KEY (401)

Cause: No x-api-key header provided

Solution: Include your API key in the request header

Football API

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

INVALID_API_KEY (401)

Cause: The provided API key is invalid or has been revoked

Solution:

• Check your API key in the dashboard
• Regenerate if necessary
• Ensure no extra spaces or characters

Rate Limit Errors

RATE_LIMIT_EXCEEDED (429)

Cause: Daily quota exceeded (applies to all sports combined)

Response:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Daily quota exceeded. Resets at midnight UTC.",
    "reset_at": "2024-01-17T00:00:00Z"
  }
}

Solution:

• Wait until the reset time
• Implement caching to reduce requests
• Consider upgrading your plan

Validation Errors

INVALID_PARAMETER (400)

Cause: Invalid or missing required parameter

Response:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Parameter 'competitionId' is required",
    "parameter": "competitionId"
  }
}

Solution: Check the API documentation for required parameters

Resource Errors

RESOURCE_NOT_FOUND (404)

Cause: The requested resource doesn’t exist

Response:

{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Competition with ID 999999 not found"
  }
}

Solution: Verify the resource ID is correct

Error Handling Examples

JavaScript

const BASE_URLS = {
  football: 'https://v2.football.sportsapipro.com',
  basketball: 'https://v2.basketball.sportsapipro.com',
  tennis: 'https://v2.tennis.sportsapipro.com',
  hockey: 'https://v2.hockey.sportsapipro.com'
};

async function fetchData(sport, endpoint) {
  const baseUrl = BASE_URLS[sport];
  
  try {
    const response = await fetch(`${baseUrl}${endpoint}`, {
      headers: { 'x-api-key': API_KEY }
    });
    
    const data = await response.json();
    
    if (!response.ok) {
      switch (response.status) {
        case 401:
          throw new Error('Invalid API key. Please check your credentials.');
        case 429:
          throw new Error(`Rate limit exceeded. Resets at ${data.error.reset_at}`);
        case 404:
          throw new Error('Resource not found.');
        default:
          throw new Error(data.error?.message || 'An error occurred');
      }
    }
    
    return data;
  } catch (error) {
    console.error(`${sport.toUpperCase()} API Error:`, error.message);
    throw error;
  }
}

// Usage
const footballGames = await fetchData('football', '/api/football/live');
const basketballGames = await fetchData('basketball', '/api/basketball/live');
const tennisMatches = await fetchData('tennis', '/api/tennis/live');

Retry Strategy

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

const BASE_URLS = {
  football: 'https://v2.football.sportsapipro.com',
  basketball: 'https://v2.basketball.sportsapipro.com',
  tennis: 'https://v2.tennis.sportsapipro.com',
  // Add any of the 20+ supported sports
};

async function fetchWithRetry(sport, endpoint, maxRetries = 3) {
  const baseUrl = BASE_URLS[sport];
    
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(`${baseUrl}${endpoint}`, {
        headers: { 'x-api-key': API_KEY }
      });
      
      if (response.status >= 500) {
        throw new Error('Server error');
      }
      
      return await response.json();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      
      const delay = Math.pow(2, attempt) * 1000;
      console.log(`Retry ${attempt + 1} for ${sport} in ${delay}ms...`);
      await new Promise(r => setTimeout(r, delay));
    }
  }
}

Multi-Sport Error Handling

When building multi-sport applications, handle errors gracefully to ensure one sport’s issues don’t affect others:

async function fetchMultiSportData() {
  const sports = ['football', 'basketball', 'tennis', 'hockey'];
  const results = { errors: [] };
  
  for (const sport of sports) {
    try {
      results[sport] = await fetchData(sport, `/api/${sport}/live`);
    } catch (error) {
      results.errors.push({ sport, error: error.message });
    }
  }
  
  return results;
}

Getting Help

If you encounter persistent errors:

Contact Support

Get help from our team