Errors¶

Every exception the library raises derives from SpotifyScraperError, so a single except SpotifyScraperError catches all library failures. The Error handling guide covers the catch patterns.

The hierarchy:

SpotifyScraperError
├── URLError
├── NetworkError
│   └── RateLimitedError
├── TokenError
├── AuthenticationError
├── NotFoundError
├── ParsingError
└── MediaError

SpotifyScraperError¶

spotify_scraper.errors.SpotifyScraperError ¶

Bases: Exception

Base class for all errors raised by SpotifyScraper.

URLError¶

spotify_scraper.errors.URLError ¶

Bases: SpotifyScraperError

Invalid Spotify URL, URI, or ID input.

NetworkError¶

spotify_scraper.errors.NetworkError ¶

NetworkError(
    message: str, *, request_url: str | None = None
)

Bases: SpotifyScraperError

Transport failure while communicating with Spotify.

Initialize with an optional URL of the failed request.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable description of the failure.	required
`request_url`	`str \| None`	URL of the request that failed, when known.	`None`

RateLimitedError¶

spotify_scraper.errors.RateLimitedError ¶

RateLimitedError(
    message: str,
    *,
    request_url: str | None = None,
    retry_after: float | None = None,
)

Bases: NetworkError

Spotify rate-limited the request (HTTP 429).

Initialize with optional request URL and server-suggested delay.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable description of the failure.	required
`request_url`	`str \| None`	URL of the request that failed, when known.	`None`
`retry_after`	`float \| None`	Seconds to wait before retrying, when the server provided a `Retry-After` hint.	`None`