Overview
FastF1 uses custom exceptions to handle various error conditions during data loading and processing. The exception hierarchy is designed to support graceful degradation during data loading while ensuring critical errors are always raised.
Exception Handling Strategy
FastF1 code can be categorized into two parts:
- Interface code - Tightly coupled with the user-facing API for short-running operations
- Data processing code - Self-contained operations that handle errors gracefully, preferring to return degraded data with warnings rather than no data at all
Default Exceptions
DataNotLoadedError
class fastf1.exceptions.DataNotLoadedError(Exception)
import fastf1 as ff1
session = ff1.get_session(2023, 'Monaco', 'R')
# Trying to access data before loading
try:
laps = session.laps # Will raise DataNotLoadedError
except ff1.exceptions.DataNotLoadedError:
print("Please load the session first")
session.load()
laps = session.laps
NoLapDataError
class fastf1.exceptions.NoLapDataError(Exception)
Failed to load session because the API did not provide any usable data.
FuzzyMatchError
class fastf1.exceptions.FuzzyMatchError(ValueError)
Ergast API Exceptions
ErgastError
class fastf1.exceptions.ErgastError(Exception)
ErgastJsonError
class fastf1.exceptions.ErgastJsonError(ErgastError)
ErgastInvalidRequestError
class fastf1.exceptions.ErgastInvalidRequestError(ErgastError)
Critical Exceptions
Critical exceptions derive from FastF1CriticalError and are designed to break through catch-all error handling during data processing.
FastF1CriticalError
class fastf1.exceptions.FastF1CriticalError(RuntimeError)
Exceptions deriving from this base class must only be used in data processing code. They must never be handled by FastF1.
RateLimitExceededError
class fastf1.exceptions.RateLimitExceededError(FastF1CriticalError)
import fastf1 as ff1
import time
try:
session = ff1.get_session(2023, 'Monaco', 'R')
session.load()
except ff1.exceptions.RateLimitExceededError:
print("Rate limit exceeded. Waiting before retry...")
time.sleep(60) # Wait 60 seconds
session.load() # Retry
Deprecated Exceptions
InvalidSessionError
Deprecated since version 3.9.0. This exception is unused and will be removed in version 3.11.0.
class fastf1.exceptions.InvalidSessionError(Exception)
No matching session can be found.
Usage Notes
Most FastF1 exceptions do not need to be explicitly caught in normal usage. The library handles errors gracefully and will typically warn the user while continuing to provide degraded data where possible.
When developing with FastF1, you may want to enable debug mode to see the full exception traceback instead of gracefully handled warnings. Set the environment variable FASTF1_DEBUG=1 or use fastf1.logger.LoggingManager.debug = True.
