Types Reference

Types

class AlbumTypes(*values)

Bases: StrEnum

The type of the album.

ALBUM = 'album'

Album.

APPEARS_ON = 'appears_on'

Appears on.

COMPILATION = 'compilation'

Compilation.

EP = 'ep'

EP.

SINGLE = 'single'

Single.

class AuthScope(*values)

Bases: StrEnum

Auth scopes for Spotify API endpoints.

Scopes provide Spotify users using third-party apps the confidence that only the information they choose to share will be shared, and nothing more.

PLAYLIST_MODIFY_PRIVATE = 'playlist-modify-private'

Manage your private playlists.

PLAYLIST_MODIFY_PUBLIC = 'playlist-modify-public'

Manage your public playlists.

PLAYLIST_READ_PRIVATE = 'playlist-read-private'

Access your private playlists.

UGC_IMAGE_UPLOAD = 'ugc-image-upload'

Upload images to Spotify on your behalf.

USER_FOLLOW_MODIFY = 'user-follow-modify'

Manage who you are following.

USER_FOLLOW_READ = 'user-follow-read'

Access your followers and who you are following.

USER_LIBRARY_MODIFY = 'user-library-modify'

Manage your saved content.

USER_LIBRARY_READ = 'user-library-read'

Access your saved content.

USER_MODIFY_PLAYBACK_STATE = 'user-modify-playback-state'

Control playback on your Spotify clients and Spotify Connect devices.

USER_READ_CURRENTLY_PLAYING = 'user-read-currently-playing'

Read your currently playing content.

USER_READ_EMAIL = 'user-read-email'

Get your real email address.

USER_READ_PLAYBACK_POSITION = 'user-read-playback-position'

Read your position in content you have played.

USER_READ_PLAYBACK_STATE = 'user-read-playback-state'

Read your currently playing content and Spotify Connect devices information.

USER_READ_PRIVATE = 'user-read-private'

Access your subscription details.

USER_READ_RECENTLY_PLAYED = 'user-read-recently-played'

Access your recently played items.

USER_TOP_READ = 'user-top-read'

Read your top artists and content.

class RepeatMode(*values)

Bases: StrEnum

Possible repeat states.

CONTEXT = 'context'

Repeat a context.

OFF = 'off'

Repeat off.

TRACK = 'track'

Repeat a track.

class SpotifyItemType(*values)

Bases: StrEnum

Spotify object types.

ALBUM = 'album'

Album.

ARTIST = 'artist'

Artist.

EPISODE = 'episode'

Episode.

PLAYLIST = 'playlist'

Playlist.

SHOW = 'show'

Show.

TRACK = 'track'

Track.

USER = 'user'

User.

type APIResponse = RawAPIResponse | JsonAPIResponse

API response type.

type JsonAPIResponse = None | int | str | bool | list[JsonAPIResponse] | dict[str, JsonAPIResponse]

JSON API response type.

type RawAPIResponse = bytes | None

Raw API response type. bytes or None.

type SpotifyAlbumURI = StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^spotify:album:[A-Za-z0-9]{22}$, ascii_only=None)]

The resource identifier of an album.

type SpotifyArtistURI = StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^spotify:artist:[A-Za-z0-9]{22}$, ascii_only=None)]

The resource identifier of an artist.

type SpotifyEpisodeURI = StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^spotify:episode:[A-Za-z0-9]{22}$, ascii_only=None)]

The resource identifier of an episode.

type SpotifyItemID = StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z0-9]{22}$, ascii_only=None)]

The base-62 identifier found at the end of the SpotifyItemURI.

type SpotifyItemURI = SpotifyAlbumURI | SpotifyArtistURI | SpotifyEpisodeURI | SpotifyPlaylistURI | SpotifyShowURI | SpotifyTrackURI | SpotifyUserURI

The resource identifier of an item.

type SpotifyLocaleID = StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z]{2}_[A-Za-z]{2}$, ascii_only=None)]

An ISO 639-1 language code and an ISO 3166-1 alpha-2 country code, joined by an underscore.

type SpotifyMarketID = StringConstraints(strip_whitespace=True, to_upper=True, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z]{2}$, ascii_only=None)]

An ISO 3166-1 alpha-2 country code.

type SpotifyPlaylistURI = StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^spotify:playlist:[A-Za-z0-9]{22}$, ascii_only=None)]

The resource identifier of a playlist.

type SpotifyShowURI = StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^spotify:show:[A-Za-z0-9]{22}$, ascii_only=None)]

The resource identifier of a show.

type SpotifyTrackURI = StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^spotify:track:[A-Za-z0-9]{22}$, ascii_only=None)]

The resource identifier of a track.

type SpotifyUserURI = StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^spotify:user:[A-Za-z0-9]*$, ascii_only=None)]

The resource identifier of an user.

Exceptions

exception SpotanticAuthAccessTokenRequestError

Bases: SpotanticAuthorizationError

Exception raised when the OAuth2 access token request fails.

This occurs when the token endpoint returns a non-200 status code, typically due to invalid authorization code, invalid client credentials, or other token request issues.

exception SpotanticAuthCodeRequestError

Bases: SpotanticAuthorizationError

Exception raised when the OAuth2 authorization code request fails.

This occurs when Spotify’s authorization endpoint returns an error parameter instead of an authorization code, typically due to user denial or invalid request parameters.

exception SpotanticAuthSecurityError

Bases: SpotanticAuthorizationError

Exception raised when a security check fails during the OAuth2 authorization flow.

This typically occurs when the state parameter in the OAuth2 callback doesn’t match the expected state, indicating a potential CSRF (Cross-Site Request Forgery) attack.

exception SpotanticAuthorizationError

Bases: SpotanticException

Base exception for authorization-related errors in the OAuth2 flow.

This is the parent class for all authentication and authorization failures including security violations, code request failures, and token request failures.

exception SpotanticException

Bases: Exception

Base exception for all custom exceptions raised in the Spotantic package.

exception SpotanticInsufficientScopeError(missing_scopes: set[AuthScope])

Bases: SpotanticException

Exception raised when the access token lacks required scopes for a request.

This exception is raised when scope validation is enabled on the client and a request requires scopes that are not granted in the current access token.

exception SpotanticInvalidResponseError

Bases: SpotanticException

Exception raised for invalid Spotify API responses (empty or deserialization fails).

Probably this should never happen. If it fails then most likely the issue is based on the Spotify API server side.

exception SpotanticResponseError(error_response: ErrorResponseModel)

Bases: HttpProcessingError, SpotanticException

Exception raised for unsuccessful Spotify API responses (non-2xx status codes).

This is the base class for specific error conditions. The error details are extracted from the Spotify API error response payload.

exception SpotanticTooManyRequests(error_response: ErrorResponseModel)

Bases: SpotanticResponseError

Exception raised when rate limiting is applied (HTTP 429 Too Many Requests).

This indicates the client has made too many requests in a short time window. The SpotanticClient with max_attempts > 1 will automatically retry with exponential backoff when this error is encountered.

exception SpotanticUnauthorizedError(error_response: ErrorResponseModel)

Bases: SpotanticResponseError

Exception raised when authentication fails (HTTP 401 Unauthorized).

This occurs when the access token is invalid, expired, or has insufficient scopes. The token should be refreshed by calling authorize() on the auth manager or enabling allow_lazy_refresh if using RefreshableAuthManager.