Exceptions

Invalid arguments raise TypeError or ValueError. Unsuccessful HTTP responses raise MermaidAPIError subclasses. An unusable response (including invalid JSON, a malformed list/detail/choices response, or a malformed zonal result) raises MermaidConnectionError, with the parsing exception retained as __cause__. Transport failures also use MermaidConnectionError.

Paginated responses must contain a results array. Optional count must be a non-negative integer or null; next must be a non-empty URL string or null. Empty arrays remain valid, and unknown model fields are still preserved.

Worker and retry counts must be integers (booleans are rejected). Coordinates, radii, and retry backoff must be finite; radii and backoff must also be non-negative. Invalid STAC input shapes raise TypeError or ValueError during preparation.

Project and detail IDs share normalization: surrounding whitespace and slashes are trimmed, empty IDs and standalone dot path segments are rejected, and internal slashes remain percent-encoded as part of the ID.

exceptions

Exception hierarchy for the MERMAID SDK.

Request and authentication failures derive from MermaidError. Invalid caller arguments raise standard TypeError or ValueError exceptions. HTTP failures are mapped to dedicated subclasses by raise_for_status.

Classes:

Name	Description
MermaidError	Base class for request and authentication errors.
MermaidConnectionError	The request produced no usable response.
AuthFlowError	An interactive login could not be completed.
AuthTimeoutError	The user did not finish the login before the flow gave up.
MermaidAPIError	The API returned an unsuccessful HTTP status code.
AuthenticationError	The credentials are missing, invalid, or insufficient (401/403).
NotFoundError	The requested resource does not exist (404).
RateLimitError	The client is being throttled (429).
ServerError	The API failed to handle the request (5xx).

Functions:

Name	Description
raise_for_status	Raise the exception matching response's status code.

DETAIL_LIMIT module-attribute

DETAIL_LIMIT = 200

MermaidError

Bases: Exception

Base class for request and authentication errors.

MermaidConnectionError

Bases: MermaidError

The request produced no usable response.

Either no response came back (DNS, TLS, timeout, reset), or the body could not be used: it was not JSON, or not the shape the endpoint answers with.

AuthFlowError

AuthFlowError(
    message: str, *, payload: dict[str, Any] | None = None
)

Bases: MermaidError

An interactive login could not be completed.

Distinct from AuthenticationError, which is the API rejecting credentials that were sent. payload holds the OAuth error body when the provider supplied one.

Attributes:

Name	Type	Description
payload	dict[str, Any]

payload instance-attribute

payload: dict[str, Any] = payload or {}

AuthTimeoutError

AuthTimeoutError(
    message: str, *, payload: dict[str, Any] | None = None
)

Bases: AuthFlowError

The user did not finish the login before the flow gave up.

Attributes:

Name	Type	Description
payload	dict[str, Any]

payload instance-attribute

payload: dict[str, Any] = payload or {}

MermaidAPIError

MermaidAPIError(
    message: str,
    *,
    status_code: int,
    url: str | None = None,
    body: Any = None,
    response: Response | None = None,
)

Bases: MermaidError

The API returned an unsuccessful HTTP status code.

Attributes:

Name	Type	Description
status_code
url
body
response

status_code instance-attribute

status_code = status_code

url instance-attribute

url = url

body instance-attribute

body = body

response instance-attribute

response = response

AuthenticationError

AuthenticationError(
    message: str,
    *,
    status_code: int,
    url: str | None = None,
    body: Any = None,
    response: Response | None = None,
)

Bases: MermaidAPIError

The credentials are missing, invalid, or insufficient (401/403).

Attributes:

Name	Type	Description
status_code
url
body
response

status_code instance-attribute

status_code = status_code

url instance-attribute

url = url

body instance-attribute

body = body

response instance-attribute

response = response

NotFoundError

NotFoundError(
    message: str,
    *,
    status_code: int,
    url: str | None = None,
    body: Any = None,
    response: Response | None = None,
)

Bases: MermaidAPIError

The requested resource does not exist (404).

Attributes:

Name	Type	Description
status_code
url
body
response

status_code instance-attribute

status_code = status_code

url instance-attribute

url = url

body instance-attribute

body = body

response instance-attribute

response = response

RateLimitError

RateLimitError(
    message: str,
    *,
    retry_after: float | None = None,
    **kwargs: Any,
)

Bases: MermaidAPIError

The client is being throttled (429).

Attributes:

Name	Type	Description
retry_after
status_code
url
body
response

retry_after instance-attribute

retry_after = retry_after

status_code instance-attribute

status_code = status_code

url instance-attribute

url = url

body instance-attribute

body = body

response instance-attribute

response = response

ServerError

ServerError(
    message: str,
    *,
    status_code: int,
    url: str | None = None,
    body: Any = None,
    response: Response | None = None,
)

Bases: MermaidAPIError

The API failed to handle the request (5xx).

Attributes:

Name	Type	Description
status_code
url
body
response

status_code instance-attribute

status_code = status_code

url instance-attribute

url = url

body instance-attribute

body = body

response instance-attribute

response = response

parse_retry_after

parse_retry_after(value: str | None) -> float | None

Parse a Retry-After header into a delay in seconds.

Both forms allowed by RFC 9110 are understood: delta-seconds and an HTTP date, which is converted into the seconds remaining from now. Anything unparseable (or already in the past) yields None.

raise_for_status

raise_for_status(response: Response) -> None

Raise the exception matching response's status code.

Successful (2xx) responses return None.