DocsError Handling

Error Handling

The Python SDK raises typed modular exceptions so AI agents using tool execution environments can reliably handle each failure mode programmatically and concisely.

Categorized Class Exceptions

ExceptionCodesWhen it fires
ModexiaAuthError401, 403Invalid, manipulated, or expired Modexia API key, or missing signature headers.
ModexiaPaymentError4xx, 5xxPayment rejected server-side: insufficient balance, token non-existence, invalid EVM recipient address, or spending policy violation.
ModexiaNetworkError—Protocol connection timeout, DNS lookup failure, or local SSL handshake failure. Represents failures entirely local or transit.

Architecting Errors in your Agent

Explicit try / except mapping allows your logic to route accordingly.

python
from modexia import (
    ModexiaClient,
    ModexiaAuthError,
    ModexiaPaymentError,
    ModexiaNetworkError,
)

client = ModexiaClient(api_key="mx_test_...")

try:
    receipt = client.transfer(recipient="0xabc...", amount=5.0)
except ModexiaAuthError:
    print("Invalid Key — please check your .env variables")
except ModexiaPaymentError as e:
    # Includes rich server metadata
    print(f"Server-side payment rejection: {e}")
except ModexiaNetworkError:
    print("Underlying HTTP/DNS context failure — queue for retry.")

Built-in automatic retry logic

The SDK internally implements smart backoff automatic retries to save overhead. Upon encountering transient structural network signals such as 500, 502, 503, and 504, the client retries requests strictly up to 3 times with an exponential backoff metric utilizing a 0.5s baseline. You do not need parallel loop retry frameworks for basic Gateway connectivity.