Skip to content

Exceptions

All custom exceptions raised by swgoh_comlink inherit from SwgohComlinkException. Catching this base class is sufficient to handle any error from the library.

from swgoh_comlink import SwgohComlink
from swgoh_comlink.exceptions import SwgohComlinkException, SwgohComlinkValueError, SwgohComlinkTypeError

comlink = SwgohComlink()

try:
    player = comlink.get_player(allycode=123)
except SwgohComlinkValueError:
    print("Invalid allycode format")
except SwgohComlinkTypeError:
    print("Invalid argument type")
except SwgohComlinkException:
    print("Comlink request failed")

HTTP errors

When comlink answers with an HTTP error status, the clients raise a SwgohComlinkHTTPError (or one of its subclasses) from the original httpx.HTTPStatusError. str(exc) is "HTTP {status}: {body}", as it has always been, so existing handlers that catch SwgohComlinkException keep working.

Exception Raised for
SwgohComlinkRateLimitError HTTP 429, or the game's Rate exceeded! refusal (sent as HTTP 502)
SwgohComlinkUnavailableError HTTP 503, comlink busy or not ready
SwgohComlinkClientError Any other 4xx, the request was rejected
SwgohComlinkHTTPError Any other error status (5xx)

Each one has these attributes:

  • status: the HTTP status code.
  • code and detail: the code and message fields of comlink's JSON error body (detail is the raw body text when the body is not JSON).
  • retry_after: the Retry-After header in seconds, or None.
  • response: the httpx.Response.

Game error codes look like GAME_<n>, and the number can differ between calls that fail for the same reason. Match on the exception class, not on code.

from swgoh_comlink import SwgohComlink
from swgoh_comlink.exceptions import (
    SwgohComlinkClientError,
    SwgohComlinkHTTPError,
    SwgohComlinkRateLimitError,
)

comlink = SwgohComlink()

try:
    player = comlink.get_player(allycode=123456789)
except SwgohComlinkRateLimitError as exc:
    print(f"Rate limited, retry in {exc.retry_after or 5} s")
except SwgohComlinkClientError as exc:
    print(f"Rejected ({exc.status} {exc.code}): {exc.detail}")
except SwgohComlinkHTTPError as exc:
    print(f"Comlink error {exc.status}")

To have the client retry rate refusals and 503 responses for you, pass a RetryPolicy.

API Reference

SwgohComlinkException

SwgohComlinkException

Bases: Exception

Base class for exceptions in this module.

SwgohComlinkValueError

SwgohComlinkValueError

Bases: SwgohComlinkException, ValueError

Raised when an argument value is invalid.

SwgohComlinkTypeError

SwgohComlinkTypeError

Bases: SwgohComlinkException, TypeError

Raised when an argument type is invalid.

SwgohComlinkHTTPError

SwgohComlinkHTTPError

Bases: SwgohComlinkException

Raised when the comlink service answers with an HTTP error status.

str(exc) is always "HTTP {status}: {body}", and the exception is raised from the originating httpx.HTTPStatusError, so code that matched on the message or on SwgohComlinkException keeps working. Use :meth:from_response to build the most specific subclass for a response.

Attributes:

Name Type Description
status

The HTTP status code.
code

The code field of a JSON error body, when present. comlink error bodies have the shape {"code": ..., "message": ...}. Codes of the form GAME_<n> vary between calls for the same failure, so match on the exception class rather than on them.
detail

The message field of a JSON error body, or the raw body text when the body is not a JSON object. None when the body is empty.
retry_after

Seconds the server asked the caller to wait, parsed from the Retry-After header (delta-seconds or HTTP-date form). None when the header is absent or unreadable. The value is not clamped.
response

The httpx.Response that carried the error, if available.

from_response(response) classmethod

Build the most specific HTTP error for an error response.

Classification, first match wins:

  1. :class:SwgohComlinkRateLimitError: HTTP 429, a RATE_LIMITED code, or a message containing "Rate exceeded" (the game's own refusal, which comlink passes through as HTTP 502).
  2. :class:SwgohComlinkUnavailableError: HTTP 503.
  3. :class:SwgohComlinkClientError: any other 4xx status.
  4. :class:SwgohComlinkHTTPError: everything else (5xx).

Parameters:

Name Type Description Default
response Response

The error response returned by httpx.

 required

Returns:

Type Description
SwgohComlinkHTTPError

An instance of the matching exception class. It is not raised.

Examples:

>>> import httpx
>>> err = SwgohComlinkHTTPError.from_response(
...     httpx.Response(502, json={"code": "GAME_6", "message": "Rate exceeded!"})
... )
>>> type(err).__name__, err.status, err.code, err.detail
('SwgohComlinkRateLimitError', 502, 'GAME_6', 'Rate exceeded!')

SwgohComlinkRateLimitError

SwgohComlinkRateLimitError

Bases: SwgohComlinkHTTPError

Raised when a request was refused for exceeding a rate limit.

Covers HTTP 429 from comlink and the game's own Rate exceeded! refusal, which arrives as HTTP 502. In both cases the call was not carried out, so re-issuing it after a pause is safe.

SwgohComlinkUnavailableError

SwgohComlinkUnavailableError

Bases: SwgohComlinkHTTPError

Raised on HTTP 503: comlink is busy or not ready and asks to be retried.

comlink usually sends a short Retry-After with this status.

SwgohComlinkClientError

SwgohComlinkClientError

Bases: SwgohComlinkHTTPError

Raised on a 4xx status other than 429: the request itself was rejected.

Retrying the same request will not succeed.