Error Handling

Error Handling

All CoogCasa APIs return consistent error responses. This guide explains the error format and how to handle common errors.

Error Response Format

All errors follow this structure:

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

Field	Type	Description
error	string	Human-readable error message
code	string	Machine-readable error code (optional)
details	object	Additional error details (optional)

HTTP Status Codes

2xx Success

Code	Description
200 OK	Request successful
201 Created	Resource created successfully
204 No Content	Success with no response body

4xx Client Errors

Code	Description
400 Bad Request	Invalid request parameters
401 Unauthorized	Missing or invalid API key
403 Forbidden	Access denied
404 Not Found	Resource doesn’t exist
405 Method Not Allowed	HTTP method not supported
429 Too Many Requests	Rate limit exceeded

5xx Server Errors

Code	Description
500 Internal Server Error	Unexpected server error
502 Bad Gateway	Upstream service error
503 Service Unavailable	Service temporarily unavailable
504 Gateway Timeout	Request timed out

Common Errors

Missing Required Parameter

GET /api/roster

{
  "error": "sport parameter required"
}

Solution: Include the required parameter.

GET /api/roster?sport=mens-basketball

Invalid Parameter Value

GET /api/schedules/sport?sport=invalid-sport

{
  "error": "Invalid sport"
}

Solution: Use a valid sport key (mens-basketball, womens-basketball, football, baseball, softball).

Resource Not Found

GET /api/game?id=999999999

{
  "error": "Game not found"
}

Solution: Verify the ID exists by listing available resources first.

Rate Limited

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": "Rate limit exceeded",
  "retryAfter": 60
}

Solution: Wait for the Retry-After period before making more requests.

Unauthorized

POST /api/trigger/schedules

{
  "error": "Unauthorized"
}

Solution: Include a valid API key header.

POST /api/trigger/schedules
X-API-Key: your-api-key

Handling Errors in Code

JavaScript/TypeScript

async function fetchSchedules() {
  try {
    const response = await fetch('https://api.coogcasa.com/sports/api/schedules');

    if (!response.ok) {
      const error = await response.json();

      switch (response.status) {
        case 400:
          console.error('Invalid request:', error.error);
          break;
        case 404:
          console.error('Not found:', error.error);
          break;
        case 429:
          console.error('Rate limited. Retry after:', error.retryAfter);
          break;
        default:
          console.error('API error:', error.error);
      }
      return null;
    }

    return await response.json();
  } catch (err) {
    console.error('Network error:', err);
    return null;
  }
}

Python

import requests

def fetch_schedules():
    try:
        response = requests.get('https://api.coogcasa.com/sports/api/schedules')
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        error = e.response.json()
        if e.response.status_code == 429:
            print(f"Rate limited. Retry after: {error.get('retryAfter')} seconds")
        else:
            print(f"API error: {error.get('error')}")
        return None
    except requests.exceptions.RequestException as e:
        print(f"Network error: {e}")
        return None

Best Practices

1. Always Check Response Status

Don’t assume requests succeed. Check the HTTP status code.

2. Implement Retry Logic

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

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

3. Respect Rate Limits

• Monitor 429 responses
• Use the Retry-After header
• Cache responses when possible

4. Provide User Feedback

Translate error codes into user-friendly messages:

function getErrorMessage(error, status) {
  switch (status) {
    case 404:
      return 'The requested item was not found.';
    case 429:
      return 'Too many requests. Please wait a moment and try again.';
    case 503:
      return 'Service temporarily unavailable. Please try again later.';
    default:
      return 'An error occurred. Please try again.';
  }
}

5. Log Errors for Debugging

Log error details for troubleshooting:

console.error('API Error', {
  url: response.url,
  status: response.status,
  error: errorBody,
  timestamp: new Date().toISOString()
});

Getting Help

If you encounter persistent errors:

1. Check status.coogcasa.com for service status
2. Search GitHub Issues
3. Open a new issue with:
   • Request URL
   • Response status and body
   • Timestamp
   • Steps to reproduce