Error Handling

Understand error responses and how to handle them in your application.

Error Response Format

All API errors follow a consistent JSON format:

{
  "success": false,
  "error": {
    "message": "A human-readable error message",
    "code": "ERROR_CODE",
    "details": {} // Optional additional context
  }
}

HTTP Status Codes

Status Code	Description	Common Causes
200	Success	Request completed successfully
400	Bad Request	Invalid parameters or malformed request
401	Unauthorized	Missing or invalid API key
404	Not Found	Resource doesn't exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error occurred

Common Error Codes

MISSING_API_KEY

No API key was provided in the request headers.

{
  "success": false,
  "error": {
    "message": "API key is required",
    "code": "MISSING_API_KEY"
  }
}

Solution: Include your API key in the X-API-Key header.

INVALID_API_KEY

The provided API key is invalid or expired.

{
  "success": false,
  "error": {
    "message": "Invalid API key",
    "code": "INVALID_API_KEY"
  }
}

Solution: Verify your API key is correct in your dashboard.

RATE_LIMIT_EXCEEDED

You've exceeded the rate limit for your API key.

{
  "success": false,
  "error": {
    "message": "Rate limit exceeded. Try again in 45 seconds.",
    "code": "RATE_LIMIT_EXCEEDED",
    "retryAfter": 45
  }
}

Solution: Wait for the duration specified in retryAfter or implement exponential backoff.

PLAYER_NOT_FOUND

The requested player doesn't exist in the database.

{
  "success": false,
  "error": {
    "message": "Player not found",
    "code": "PLAYER_NOT_FOUND"
  }
}

Solution: Verify the player slug or ID is correct. Use the search endpoint to find players.

INVALID_PARAMETERS

One or more query parameters are invalid or out of range.

{
  "success": false,
  "error": {
    "message": "Invalid parameter: limit must be between 1 and 100",
    "code": "INVALID_PARAMETERS",
    "details": {
      "parameter": "limit",
      "value": 500,
      "constraint": "Must be between 1 and 100"
    }
  }
}

Solution: Check the API documentation for valid parameter values and constraints.

Error Handling Best Practices

Always Check Response Status

Check both HTTP status codes and the success field in the response.

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

if (!response.ok) {
  const error = await response.json();
  console.error('API Error:', error.error.message);

  // Handle specific error codes
  switch (error.error.code) {
    case 'MISSING_API_KEY':
    case 'INVALID_API_KEY':
      // Update credentials
      break;
    case 'RATE_LIMIT_EXCEEDED':
      // Wait and retry
      break;
    case 'PLAYER_NOT_FOUND':
      // Show not found message
      break;
  }
}

Implement Retry Logic

Retry failed requests with exponential backoff for transient errors.

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);

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

      // Don't retry client errors (4xx except 429)
      if (response.status >= 400 && response.status < 500 && response.status !== 429) {
        throw new Error(`Client error: ${response.status}`);
      }

      // Exponential backoff
      if (i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
      }
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

Log Errors for Debugging

Keep detailed logs of API errors to help diagnose issues.

try {
  const data = await fetchPlayer('lebron-james');
} catch (error) {
  // Log full error details
  console.error('Failed to fetch player:', {
    timestamp: new Date().toISOString(),
    endpoint: '/api/players/lebron-james',
    error: error.message,
    code: error.code,
    details: error.details
  });

  // Show user-friendly message
  showErrorMessage('Unable to load player data. Please try again.');
}

Need Help with an Error?

If you're experiencing persistent errors or need clarification about an error code, please open an issue on GitHub with details about the error, your request, and any relevant logs.