API Client Configuration

The DefaultApiClient is used to perform the actual HTTP requests. It also manages rate-limiting and retries.

If you need more functionality, you can subclass it. To use a custom client, set default_client or use the client parameter in each API method wrapper.

exception lichess.api.ApiError

The base class for API exceptions.

exception lichess.api.ApiHttpError(http_status, url, response_text)

The class for API exceptions caused by an HTTP error code.

class lichess.api.DefaultApiClient(base_url=None, max_retries=None)

The default API client, with immediate HTTP calls and basic rate-limiting functionality.

base_url = 'https://lichess.org/'

The base lichess API URL.

This does not include the /api/ prefix, since some APIs don’t use it.

max_retries = -1

The maximum number of retries after rate-limiting before an exception is raised. -1 for infinite retries.

call(path, params=None, post_data=None, auth=None, format=<lichess.format._Json object>, object_type='public_api')

Makes an API call, prepending base_url to the provided path. HTTP GET is used unless post_data is provided.

Consecutive calls use a 1s delay. If HTTP 429 is received, retries after a 1min delay.

on_rate_limit(url, retry_count)

A handler called when HTTP 429 is received.

Raises an exception when max_retries is exceeded.


A handler called when HTTP 502 or HTTP 503 is received.

Raises an exception when max_retries is exceeded.

lichess.api.default_client = <lichess.api.DefaultApiClient object>

The client object used to communicate with the lichess API.

Initially set to an instance of DefaultApiClient.