Exceptions

The library defines custom exceptions for different error scenarios.

Exception Hierarchy

VlrdevapiError (base exception)
├── NetworkError
└── RateLimitError

Exception Classes

VlrdevapiError

class vlrdevapi.exceptions.VlrdevapiError(message: str, url: str | None = None, status_code: int | None = None, context: dict[str, Any] | None = None)[source]

Base exception for vlrdevapi errors.

Parameters:

message – Error message
url – URL that caused the error (optional)
status_code – HTTP status code if applicable (optional)
context – Additional context information (optional)

__init__(message: str, url: str | None = None, status_code: int | None = None, context: dict[str, Any] | None = None) → None[source]

Base exception for all library errors.

NetworkError

class vlrdevapi.exceptions.NetworkError(message: str, url: str | None = None, status_code: int | None = None, context: dict[str, Any] | None = None)[source]: Raised when network requests fail.

Raised when network requests fail due to:

Connection timeouts
HTTP errors (4xx, 5xx)
DNS resolution failures
SSL/TLS errors

RateLimitError

class vlrdevapi.exceptions.RateLimitError(message: str, url: str | None = None, status_code: int | None = None, context: dict[str, Any] | None = None)[source]: Raised when rate limited by the server.

Raised when the server returns HTTP 429 (Too Many Requests).

Usage Examples

Basic Error Handling

import vlrdevapi as vlr
from vlrdevapi.exceptions import NetworkError

try:
    events = vlr.events.list_events()
except NetworkError as e:
    print(f"Failed to fetch events: {e}")

Handle Rate Limiting

import vlrdevapi as vlr
from vlrdevapi.exceptions import RateLimitError
import time

try:
    matches = vlr.matches.upcoming()
except RateLimitError:
    print("Rate limited. Waiting before retry...")
    time.sleep(60)
    matches = vlr.matches.upcoming()

Catch All Library Errors

import vlrdevapi as vlr
from vlrdevapi.exceptions import VlrdevapiError

try:
    profile = vlr.players.profile(player_id=4164)
except VlrdevapiError as e:
    print(f"API error: {e}")

Specific Error Handling

import vlrdevapi as vlr
from vlrdevapi.exceptions import NetworkError, RateLimitError

try:
    events = vlr.events.list_events()
except RateLimitError:
    print("Rate limited. Please wait and try again.")
except NetworkError as e:
    print(f"Network error: {e}")
    print("Check your internet connection.")

Retry Logic

import vlrdevapi as vlr
from vlrdevapi.exceptions import NetworkError, RateLimitError
import time

def fetch_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError:
            if attempt < max_retries - 1:
                wait_time = 60 * (attempt + 1)
                print(f"Rate limited. Waiting {wait_time}s...")
                time.sleep(wait_time)
            else:
                raise
        except NetworkError as e:
            if attempt < max_retries - 1:
                print(f"Network error: {e}. Retrying...")
                time.sleep(5)
            else:
                raise

# Use retry logic
events = fetch_with_retry(lambda: vlr.events.list_events())

Logging Errors

import vlrdevapi as vlr
from vlrdevapi.exceptions import VlrdevapiError
import logging

logging.basicConfig(level=logging.ERROR)
logger = logging.getLogger(__name__)

try:
    matches = vlr.matches.upcoming()
except VlrdevapiError as e:
    logger.error(f"Failed to fetch matches: {e}", exc_info=True)

Best Practices

Always Handle Exceptions

Network operations can fail. Always wrap API calls in try-except blocks:

import vlrdevapi as vlr
from vlrdevapi.exceptions import NetworkError

try:
    data = vlr.events.list_events()
except NetworkError:
    # Handle error gracefully
    data = []

Be Specific

Catch specific exceptions when possible:

import vlrdevapi as vlr
from vlrdevapi.exceptions import RateLimitError, NetworkError

try:
    data = vlr.events.list_events()
except RateLimitError:
    # Handle rate limiting specifically
    pass
except NetworkError:
    # Handle other network errors
    pass

Respect Rate Limits

When rate limited, wait before retrying:

import vlrdevapi as vlr
import time
from vlrdevapi.exceptions import RateLimitError

try:
    data = vlr.events.list_events()
except RateLimitError:
    time.sleep(60)  # Wait at least 60 seconds
    data = vlr.events.list_events()

Use Library Caching

The library includes built-in caching to reduce requests:

import vlrdevapi as vlr

# First call fetches from network
events1 = vlr.events.list_events()

# Second call uses cache (no network request)
events2 = vlr.events.list_events()

# Clear cache when you need fresh data
vlr.fetcher.clear_cache()
events3 = vlr.events.list_events()  # Fetches from network