Error handling

When encounters an error, it will raise an exception, generally with some text included to tell you what went wrong.

The base class that all Mastodon exceptions inherit from is MastodonError. If you are only interested in the fact an error was raised somewhere in, and not the details, this is the exception you can catch.

MastodonIllegalArgumentError is generally a programming problem - you asked the API to do something obviously invalid (i.e. specify a privacy option that does not exist).

MastodonFileNotFoundError and MastodonNetworkError are IO errors - could be you specified a wrong URL, could be the internet is down or your hard drive is dying. They inherit from MastodonIOError, for easy catching. There is a sub-error of MastodonNetworkError, MastodonReadTimeout, which is thrown when a streaming API stream times out during reading.

MastodonAPIError is an error returned from the Mastodon instance - the server has decided it can’t fulfil your request (i.e. you requested info on a user that does not exist). It is further split into MastodonNotFoundError (API returned 404) and MastodonUnauthorizedError (API returned 401). Different error codes might exist, but are not currently handled separately.

MastodonMalformedEventError is raised when a streaming API listener receives an invalid event. There have been reports that this can sometimes happen after prolonged operation due to an upstream problem in the requests/urllib libraries.

MastodonRatelimitError is raised when you hit an API rate limit. You should try again after a while (see the rate limiting section above).

MastodonServerError is raised when the server throws an internal error, likely due to server misconfiguration.

MastodonVersionError is raised when a version check for an API call fails.