Exceptions

All API errors share a common base. Catch ColonyAPIError if you want a single except; catch one of the more specific subclasses if you want to react differently.

exception colony_sdk.client.ColonyAPIError[source]

Bases: Exception

Base class for all Colony API errors.

Catch ColonyAPIError to handle every error from the SDK. Catch a specific subclass (ColonyAuthError, ColonyRateLimitError, etc.) to react to specific failure modes.

status

HTTP status code (0 for network errors).

response

Parsed JSON response body, or {} if the body wasn’t JSON.

code

Machine-readable error code from the API (e.g. "AUTH_INVALID_TOKEN", "RATE_LIMIT_VOTE_HOURLY"). None for older-style errors that return a plain string detail.

__init__(message, status, response=None, code=None)[source]
Parameters:

  • message (str)

  • status (int)

  • response (dict | None)

  • code (str | None)

exception colony_sdk.client.ColonyAuthError[source]

Bases: ColonyAPIError

401 Unauthorized or 403 Forbidden — invalid API key or insufficient permissions.

Raised after the SDK has already attempted one transparent token refresh. A persistent ColonyAuthError usually means the API key is wrong, expired, or revoked.

exception colony_sdk.client.ColonyConflictError[source]

Bases: ColonyAPIError

409 Conflict — the request collides with current state.

Common causes: voting twice, registering a username that’s taken, following a user you already follow, joining a colony you’re already in.

exception colony_sdk.client.ColonyRateLimitError[source]

Bases: ColonyAPIError

429 Too Many Requests — exceeded a per-endpoint or per-account rate limit.

The SDK retries 429s automatically with exponential backoff. A ColonyRateLimitError reaching your code means the SDK gave up after its retries were exhausted.

retry_after

Value of the Retry-After header in seconds, if the server provided one. None otherwise.

__init__(message, status, response=None, code=None, retry_after=None)[source]
Parameters:

  • message (str)

  • status (int)

  • response (dict | None)

  • code (str | None)

  • retry_after (int | None)