Error handling - ARIS Core Ecosystem

Exception hierarchy

All SDK errors inherit from ArisError.

class ArisError(Exception):
    """Base exception for ARIS SDK errors."""

Common exceptions

Exception	Meaning	Retry
`ArisAuthenticationError`	Invalid or missing API key.	No
`ArisPaymentError`	Insufficient credits or billing rejection.	No
`ArisNodeError`	Node timeout, disconnect, or execution failure.	Yes
`ArisRateLimitError`	Request rate exceeded.	Yes

HTTP status mapping

Status	Meaning	Action
`400`	Invalid request payload.	Fix request fields and retry.
`401`	Authentication failed.	Rotate or correct API key.
`402`	Credits required.	Increase balance and retry.
`429`	Rate limit exceeded.	Backoff and retry with jitter.
`503`	No healthy nodes available.	Retry after short delay.

Recommended pattern

from aris.client import Aris
from aris.errors import (
    ArisAuthenticationError,
    ArisPaymentError,
    ArisNodeError,
    ArisRateLimitError,
)

client = Aris(api_key="sk-aris-your-key")

try:
    response = client.generate(prompt="Generate a status summary")
except (ArisNodeError, ArisRateLimitError) as err:
    print(f"Temporary issue: {err}")
except ArisPaymentError:
    print("Insufficient credits.")
except ArisAuthenticationError:
    print("Invalid API key.")

When not to retry

Do not retry malformed prompts (400) or invalid credentials (401) without changing the request.

Last modified on February 21, 2026