Errors

Web errors for Authorisation and Client.

`HTTPError`	Base error for all web status errors.
`ClientError`	4xx - Base client error.
`ServerError`	5xx - Base server error.
`BadRequest`	400 - Bad request.
`RefreshTokenInvalid`	400 - Invalid grant when refreshing a token.
`Unauthorised`	401 - Unauthorised.
`Forbidden`	403 - Forbidden.
`NotFound`	404 - Not found.
`TooManyRequests`	429 - Too many requests.
`InternalServerError`	500 - Internal server error.
`BadGateway`	502 - Bad gateway.
`ServiceUnavailable`	503 - Service unavailable.

Clients facing the Web API raise errors when recieving bad status codes. Only errors documented in the Web API documentation are expected and provided. Other exceptions are raised as ClientError or ServerError.

import tekore as tk

conf = tk.config_from_environment()
token = tk.request_client_token(*conf[:2])
spotify = tk.Spotify(token)

try:
    spotify.album('not-a-real-album')
except tk.BadRequest:
    print('Whoops, bad request!')
except tk.HTTPError:
    print('Something is seriously wrong.')

Error objects also contain the relevant Request and Response objects for closer inspection.

try:
    spotify.album('not-a-real-album')
except tk.BadRequest as ex:
    print(str(ex))
    print(ex.request)
    print(ex.response)

When refreshing a user token fails because the refresh token has expired or been revoked, for example due to Spotify’s six-month refresh token expiration, a RefreshTokenInvalid error is raised. It is a subclass of BadRequest, so it can be caught specifically to trigger a new authorisation, while existing except BadRequest handlers keep working.

class tekore.HTTPError(message, request, response)

Bases: Exception

Base error for all web status errors.

Parameters:

message (str)
request (Request)
response (Response)

request: request that led to the error

response: response from the web server

class tekore.ClientError(message, request, response)

Bases: HTTPError

4xx - Base client error.

Parameters:

message (str)
request (Request)
response (Response)

class tekore.ServerError(message, request, response)

Bases: HTTPError

5xx - Base server error.

Parameters:

message (str)
request (Request)
response (Response)

class tekore.BadRequest(message, request, response)

Bases: ClientError

400 - Bad request.

The request could not be understood by the server due to malformed syntax.

Parameters:

message (str)
request (Request)
response (Response)

class tekore.RefreshTokenInvalid(message, request, response)

Bases: BadRequest

400 - Invalid grant when refreshing a token.

Raised when the authorisation server rejects a token request with an invalid_grant OAuth error. For user tokens this most commonly means that the refresh token has expired or been revoked, e.g. because of Spotify’s six-month refresh token expiration. When this is raised the user should be prompted to authorise the application again.

This is a subclass of BadRequest.

Parameters:

message (str)
request (Request)
response (Response)

class tekore.Unauthorised(message, request, response)

Bases: ClientError

401 - Unauthorised.

The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

The scopes associated with the call are attached to this class.

Parameters:

message (str)
request (Request)
response (Response)

optional_scope: str

required_scope: str

scope: str

class tekore.Forbidden(message, request, response)

Bases: ClientError

403 - Forbidden.

The server understood the request, but is refusing to fulfill it.

Parameters:

message (str)
request (Request)
response (Response)

class tekore.NotFound(message, request, response)

Bases: ClientError

404 - Not found.

The requested resource could not be found. This error can be due to a temporary or permanent condition.

Parameters:

message (str)
request (Request)
response (Response)

class tekore.TooManyRequests(message, request, response)

Bases: ClientError

429 - Too many requests.

Rate limiting has been applied.

Parameters:

message (str)
request (Request)
response (Response)

class tekore.InternalServerError(message, request, response)

Bases: ServerError

500 - Internal server error.

You should never receive this error because the clever coders at Spotify catch them all… But if you are unlucky enough to get one, please report it to Spotify through their GitHub (spotify/web-api).

Parameters:

message (str)
request (Request)
response (Response)

class tekore.BadGateway(message, request, response)

Bases: ClientError

502 - Bad gateway.

The server was acting as a gateway or proxy and received an invalid response from the upstream server.

Parameters:

message (str)
request (Request)
response (Response)

class tekore.ServiceUnavailable(message, request, response)

Bases: ClientError

503 - Service unavailable.

The server is currently unable to handle the request due to a temporary condition which will be alleviated after some delay. You can choose to resend the request again.

Parameters:

message (str)
request (Request)
response (Response)