📔Error codes

Whenever you receive an unexpected response or experience unexpected behavior, check the HTTP response code and use this guide to troubleshoot the issue.

Quick reference

Code	Error	When It Happens	Quick Fix
200	OK	Request succeeded	No action needed ✅
400	Bad Request	Malformed request, invalid parameters	Check request syntax and parameters
401	Unauthorized	Missing or invalid API token	Verify your API token
403	Forbidden	Accessing unauthorized resource	Check your plan access
404	Not Found	Resource doesn't exist	Verify the ID or endpoint
429	Too Many Requests	Rate limit exceeded	Reduce request frequency or upgrade plan
500	Internal Server Error	Server-side issue	Contact support if persistent

💡 Pro tip: Always implement proper error handling in your code to catch and handle these errors gracefully.

Detailed error explanations

Click an error code below for detailed troubleshooting information:

200: OK ✅

What it means: Your request was successful and data has been returned.

Response structure:

{
  "data": { ... },
  "subscription": [ ... ],
  "rate_limit": { ... },
  "timezone": "UTC"
}

Best practices:

• Always check that data field exists before processing

• Store rate_limit information to monitor your usage

• Handle empty data arrays appropriately

📖 Learn more: Understanding API Responses

400: Bad request ❌

What it means: There's a problem with how your request is formatted or the parameters you're using.

Common causes:

1. Invalid query parameters

# ❌ Wrong
GET /fixtures?invalid_param=123

# ✅ Correct
GET /fixtures?api_token=YOUR_TOKEN&filters=fixtureLeagues:501

2. Malformed include syntax

# ❌ Wrong - space in include
GET /fixtures/123?include=participants, events

# ✅ Correct - no spaces
GET /fixtures/123?include=participants;events

3. Invalid filter syntax

# ❌ Wrong - incorrect format
GET /fixtures?filters=league=501

# ✅ Correct - proper format
GET /fixtures?filters=fixtureLeagues:501

4. Invalid timezone

# ❌ Wrong - invalid timezone
GET /fixtures?timezone=NewYork

# ✅ Correct - proper timezone format
GET /fixtures?timezone=America/New_York

Example error response:

{
  "message": "The given data was invalid.",
  "errors": {
    "filters": [
      "The filters format is invalid."
    ]
  }
}

How to fix:

1. Check parameter spelling - Use exact names from documentation

2. Verify filter syntax - See Filter Tutorial

3. Validate include format - Use semicolons, no spaces

4. Test with minimal parameters - Remove optional params to isolate issue

Code example (Error handling):

try {
  const response = await fetch(url);
  const data = await response.json();
  
  if (response.status === 400) {
    console.error('Bad Request:', data.message);
    console.error('Errors:', data.errors);
    // Fix your request parameters
  }
} catch (error) {
  console.error('Request failed:', error);
}

📖 Related: Request Options | Filter Tutorial

401: Unauthorized 🔒

What it means: Your API token is missing, invalid, or expired.

Common causes:

1. Missing API token

# ❌ Wrong - no token
GET https://api.sportmonks.com/v3/football/fixtures

# ✅ Correct - token included
GET https://api.sportmonks.com/v3/football/fixtures?api_token=YOUR_TOKEN

2. Token typo or extra spaces

# ❌ Wrong - extra space
?api_token= YOUR_TOKEN

# ✅ Correct - no spaces
?api_token=YOUR_TOKEN

3. Using test token in production

# ❌ Wrong environment
Production URL + Test Token = 401 Error

# ✅ Correct - matching environment
Production URL + Production Token

4. Revoked or expired token

• Token was regenerated in MySportmonks

• Token was manually revoked

• Account subscription expired

Example error response:

{
  "error": "Unauthenticated.",
  "message": "Please provide a valid API token"
}

How to fix:

1. Verify your token:

   • Go to MySportmonks Dashboard

   • Navigate to API tokens section

   • Copy the correct token (don't type it manually)

2. Test with cURL:

curl "https://api.sportmonks.com/v3/football/fixtures?api_token=YOUR_TOKEN"

1. Check token format in code:

// ✅ Correct implementation
const API_TOKEN = process.env.SPORTMONKS_TOKEN; // From environment variable
const url = `https://api.sportmonks.com/v3/football/fixtures?api_token=${API_TOKEN}`;

1. Common mistakes to avoid:

   • ❌ Hardcoding tokens in frontend code (security risk)

   • ❌ Including quotes around the token

   • ❌ Adding spaces before or after the token

   • ❌ Using header authentication (use query parameter instead)

Security best practices:

// ✅ Good - Server-side only
// backend/api.js
const SPORTMONKS_TOKEN = process.env.SPORTMONKS_TOKEN;

// ❌ Bad - Exposed in frontend
// frontend/app.js
const SPORTMONKS_TOKEN = 'abcd1234...'; // Visible to users!

📖 Related: Authentication Guide | Best Practices

403: Forbidden 🚫

What it means: Your API token is valid, but you don't have permission to access this resource.

Common Causes:

1. Resource not in your plan

# Your plan: Free Plan (Danish & Scottish leagues only)
GET /fixtures?filters=fixtureLeagues:8 # Premier League
# Result: 403 Forbidden

2. Feature not available in your tier

# Your plan: Basic (no xG access)
GET /fixtures/123?include=xGFixture
# Result: 403 Forbidden

3. Accessing premium endpoints

# Predictions endpoint requires add-on
GET /predictions/probabilities/fixtures/123
# Result: 403 if you don't have Predictions add-on

Example Error Response:

{
  "error": "Access Denied",
  "message": "This resource is not available in your current subscription.",
  "resource": "xGFixture",
  "plan_required": "Standard or higher"
}

How to fix:

1. Check your plan access:

   • Go to MySportmonks Dashboard

   • Review "My Subscriptions" section

   • Check which leagues and features are included

2. Verify resource availability:

// Check if resource is accessible
try {
  const response = await fetch(url);
  
  if (response.status === 403) {
    console.log('Resource not available in your plan');
    console.log('Upgrade at: https://www.sportmonks.com/football-api/#plans-pricing');
  }
} catch (error) {
  console.error(error);
}

1. Common 403 scenarios:

Scenario	Plan needed	Solution
Access Premier League	Standard+	Upgrade or filter to your leagues
Use xG data	Standard+	Upgrade or remove xG includes
Access Predictions	Predictions add-on	Add predictions to your plan
Live odds	Odds package	Subscribe to odds package

1. Workarounds (if you can't upgrade):

   • Filter requests to only leagues in your plan

   • Remove premium includes from requests

   • Check Data Features by League

📖 Related: Plan Features | Data Features per League

404: Not found 🔍

What it means: The resource you're trying to access doesn't exist.

Common Causes:

1. Invalid ID

# ❌ Wrong - fixture doesn't exist
GET /fixtures/99999999999

# ✅ Correct - use valid fixture ID
GET /fixtures/18535517

2. Wrong endpoint path

# ❌ Wrong - typo in endpoint
GET /v3/football/fixture/123  # "fixture" should be "fixtures"

# ✅ Correct - proper endpoint
GET /v3/football/fixtures/123

3. Resource was deleted

# Fixture was removed from database
# (e.g., cancelled match, placeholder fixture)
GET /fixtures/12345
# Result: 404 Not Found

Example error response:

{
  "error": "Not Found",
  "message": "The requested resource could not be found.",
  "resource_type": "fixture",
  "resource_id": "99999999"
}

How to fix:

1. Verify the ID exists:

// Search for the resource first
const searchResponse = await fetch(
  'https://api.sportmonks.com/v3/football/fixtures/search/Celtic?api_token=YOUR_TOKEN'
);
const results = await searchResponse.json();

// Then use a valid ID from results
const fixtureId = results.data[0].id;

1. Check endpoint spelling:

// ✅ Correct endpoints
/v3/football/fixtures/{id}
/v3/football/teams/{id}
/v3/football/players/{id}
/v3/football/leagues/{id}

// ❌ Common mistakes
/v3/football/fixture/{id}   // Missing 's'
/v3/soccer/fixtures/{id}    // Wrong sport name
/v3/football/match/{id}     // Wrong entity name

1. Handle 404 gracefully:

async function getFixture(fixtureId) {
  try {
    const response = await fetch(
      `https://api.sportmonks.com/v3/football/fixtures/${fixtureId}?api_token=YOUR_TOKEN`
    );
    
    if (response.status === 404) {
      console.log('Fixture not found');
      return null; // Return null instead of throwing error
    }
    
    return await response.json();
  } catch (error) {
    console.error('Request failed:', error);
    throw error;
  }
}

1. Use ID finder tool:

   • Visit ID Finder

   • Search for teams, players, leagues, etc.

   • Get valid IDs for your requests

📖 Related: API Structure | Endpoints Reference

429: Too many requests ⏱️

What it means: You've exceeded your plan's rate limit.

Common causes:

1. Making requests too quickly

// ❌ Wrong - rapid fire requests
for (let i = 0; i < 1000; i++) {
  fetch(url); // Hitting rate limit!
}

// ✅ Correct - with delay
for (let i = 0; i < 1000; i++) {
  await fetch(url);
  await sleep(100); // 100ms delay
}

2. Inefficient API usage

// ❌ Wrong - separate requests
const team1 = await fetch('/teams/53');
const team2 = await fetch('/teams/62');
const fixture = await fetch('/fixtures/123');
// 3 API calls

// ✅ Correct - use includes
const fixture = await fetch('/fixtures/123?include=participants');
// 1 API call with all data

3. Not caching reference data

// ❌ Wrong - fetching types every time
for (const stat of statistics) {
  const type = await fetch(`/types/${stat.type_id}`); // Wasteful!
}

// ✅ Correct - fetch once and cache
const allTypes = await fetch('/types');
const typesMap = new Map(allTypes.data.map(t => [t.id, t]));
// Use cached types for lookups

Example error response:

{
  "error": "Too Many Requests",
  "message": "Rate limit of 3000 requests per hour exceeded.",
  "retry_after": 1847,
  "rate_limit": {
    "remaining": 0,
    "total": 3000,
    "resets_in": "30:47"
  }
}

How to fix:

1. Check your rate limit: Every successful response includes rate limit info:

{
  "data": { ... },
  "rate_limit": {
    "resets_in_seconds": 1847,
    "remaining": 2847,
    "requested_entity": "Fixture"
  }
}

2. Implement rate limiting:

class RateLimiter {
  constructor(maxRequests, perSeconds) {
    this.maxRequests = maxRequests;
    this.perSeconds = perSeconds;
    this.requests = [];
  }
  
  async throttle() {
    const now = Date.now();
    this.requests = this.requests.filter(time => now - time < this.perSeconds * 1000);
    
    if (this.requests.length >= this.maxRequests) {
      const oldestRequest = this.requests[0];
      const waitTime = (this.perSeconds * 1000) - (now - oldestRequest);
      await new Promise(resolve => setTimeout(resolve, waitTime));
    }
    
    this.requests.push(Date.now());
  }
}

// Usage
const limiter = new RateLimiter(3000, 3600); // 3000 requests per hour

async function makeRequest(url) {
  await limiter.throttle();
  return fetch(url);
}

3. Implement retry with exponential backoff:

async function fetchWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url);
      
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
        console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
        await sleep(retryAfter * 1000);
        continue;
      }
      
      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000);
    }
  }
}

4. Optimisation strategies:

Strategy	Savings	How
Use includes	50-80%	Combine related data in one request
Cache reference data	30-50%	Store types, states, leagues locally
Batch operations	40-60%	Use multi-ID endpoints where available
Smart polling	30-40%	Only poll live matches, reduce frequency

Example - Before & after optimisation:

// ❌ Before: 50 API calls for 10 fixtures
for (const fixtureId of fixtureIds) {
  const fixture = await fetch(`/fixtures/${fixtureId}`);
  const team1 = await fetch(`/teams/${fixture.team1_id}`);
  const team2 = await fetch(`/teams/${fixture.team2_id}`);
  const events = await fetch(`/fixtures/${fixtureId}/events`);
  const stats = await fetch(`/fixtures/${fixtureId}/statistics`);
}

// ✅ After: 2 API calls for 10 fixtures
const fixtures = await fetch(
  `/fixtures/multi/${fixtureIds.join(',')}?include=participants;events;statistics.type`
);
// Then fetch types once and cache
const types = await fetch('/types');

5. Monitor your usage:

function logRateLimit(response) {
  const remaining = response.rate_limit.remaining;
  const total = response.rate_limit.resets_in_seconds;
  
  console.log(`Rate limit: ${remaining} requests remaining`);
  
  if (remaining < 100) {
    console.warn('⚠️ Low on API calls! Optimize your requests.');
  }
}

📖 Related: Rate Limiting Guide | Includes Tutorial | Best Practices

500: Internal server error 🔧

What it means: Something went wrong on our servers.

When this happens:

• Temporary server issue

• Database connectivity problem

• Unexpected data format causing server error

• Service maintenance or deployment

Example error response:

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred. Our team has been notified.",
  "error_id": "err_abc123xyz"
}

How to handle:

1. Implement retry logic:

async function fetchWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url);
      
      if (response.status === 500) {
        if (i < maxRetries - 1) {
          console.log(`Server error. Retrying (${i + 1}/${maxRetries})...`);
          await sleep(Math.pow(2, i) * 1000); // Exponential backoff
          continue;
        }
      }
      
      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

2. Check API status:

• Visit Sportmonks Status Page (if available)

• Check for maintenance announcements

• Verify if issue is widespread or isolated

3. Contact support (if persistent):

if (response.status === 500) {
  const errorDetails = {
    timestamp: new Date().toISOString(),
    endpoint: url,
    error_id: response.error_id,
    request_id: response.headers.get('X-Request-ID')
  };
  
  console.error('Persistent 500 error:', errorDetails);
  // Send to support: [email protected]
}

4. Graceful degradation:

async function getFixtures(fallbackData) {
  try {
    const response = await fetch(url);
    
    if (response.status === 500) {
      console.warn('Server error. Using cached data.');
      return fallbackData; // Use cached or default data
    }
    
    return await response.json();
  } catch (error) {
    console.error('Complete failure:', error);
    return fallbackData;
  }
}

📖 Related: Best Practices | Contact Support

Common error scenarios

Scenario 1: "Data is missing"

Problem: Response is 200 OK but data is empty or missing fields.

Not an error code issue! This is usually because:

• Resource not in your plan → Check plan access

• Missing includes → Add necessary includes to request

• Filtering too strict → Review filter syntax

Scenario 2: CORS Errors (Frontend)

Problem: "CORS policy: No 'Access-Control-Allow-Origin' header"

Solution: This isn't an API error - use a backend proxy:

// ❌ Don't do this - frontend direct call
fetch('https://api.sportmonks.com/v3/football/fixtures?api_token=YOUR_TOKEN')

// ✅ Do this - call your backend
fetch('/api/fixtures') // Your backend proxies to Sportmonks

📖 Learn more: CORS Best Practices

Scenario 3: Timeout errors

Problem: Request times out with no response.

Solutions:

• Reduce includes complexity

• Add pagination to large requests

• Check your network connectivity

• Increase timeout threshold in your code

Error handling code examples

Complete Example (JavaScript/Node.js)

JavaScript

class SportmonksAPI {
  constructor(apiToken) {
    this.apiToken = apiToken;
    this.baseURL = 'https://api.sportmonks.com/v3/football';
  }
  
  async request(endpoint, params = {}) {
    const url = new URL(`${this.baseURL}${endpoint}`);
    url.searchParams.append('api_token', this.apiToken);
    
    Object.entries(params).forEach(([key, value]) => {
      url.searchParams.append(key, value);
    });
    
    try {
      const response = await fetch(url.toString());
      const data = await response.json();
      
      // Handle different status codes
      switch (response.status) {
        case 200:
          return { success: true, data: data.data };
          
        case 400:
          throw new Error(`Bad Request: ${data.message || 'Invalid parameters'}`);
          
        case 401:
          throw new Error('Unauthorized: Check your API token');
          
        case 403:
          throw new Error(`Forbidden: ${data.message || 'Resource not in your plan'}`);
          
        case 404:
          throw new Error(`Not Found: Resource doesn't exist`);
          
        case 429:
          const retryAfter = data.retry_after || 60;
          throw new Error(`Rate Limited: Retry after ${retryAfter} seconds`);
          
        case 500:
          throw new Error('Server Error: Try again later or contact support');
          
        default:
          throw new Error(`Unexpected error: ${response.status}`);
      }
    } catch (error) {
      console.error('API Error:', error.message);
      throw error;
    }
  }
}

// Usage
const api = new SportmonksAPI(process.env.SPORTMONKS_TOKEN);

try {
  const fixtures = await api.request('/fixtures', {
    filters: 'fixtureLeagues:501',
    include: 'participants'
  });
  console.log(fixtures);
} catch (error) {
  // Handle error appropriately in your app
  console.error('Failed to fetch fixtures:', error);
}

Python

See also

• Rate Limiting Guide - Understand and optimize rate limits

• Authentication - Setting up API access

• Best Practices - Build robust applications

• Request Options - Available query parameters

• Contact Support - Get help when needed

Need help? Contact [email protected] or use the chat widget.