Error Handling

All SDK exceptions inherit from QarionError and carry structured information about the failure.

Exception Hierarchy

Exception Reference

Exception	HTTP Status	When It's Raised
QarionError	—	Base class for all SDK errors
AuthenticationError	401	Invalid or missing API key
PermissionDeniedError	403	Insufficient permissions for the operation
NotFoundError	404	Resource does not exist
ValidationError	400 / 422	Invalid request payload
ConflictError	409	Resource conflict (e.g., duplicate slug)
ServerError	5xx	Platform-side failure
TimeoutError	—	Request exceeded the configured timeout

Error Attributes

Every exception carries two useful attributes:

Attribute	Type	Description
status_code	int | None	HTTP status code (if applicable)
detail	Any	Detailed error info from the API response

Usage Patterns

Catching Specific Errors

from qarion import QarionClient, NotFoundError, AuthenticationError, ValidationError

async with QarionClient(api_key="qk_...") as client:
    try:
        product = await client.products.get("my-space", "nonexistent")
    except NotFoundError as e:
        print(f"Not found (HTTP {e.status_code}): {e.detail}")
    except AuthenticationError:
        print("Invalid API key")
    except ValidationError as e:
        print(f"Bad request: {e.detail}")

Catching All SDK Errors

from qarion import QarionClient, QarionError

async with QarionClient() as client:
    try:
        result = await client.quality.trigger("my-space", "check-slug")
    except QarionError as e:
        print(f"SDK error [{e.status_code}]: {e}")

Retry on Conflict

from qarion import QarionSyncClient, ConflictError

with QarionSyncClient() as client:
    try:
        product = client.products.create(
            "my-space", name="My Product", slug="my-product"
        )
    except ConflictError:
        # Slug already exists — fetch the existing product instead
        product = client.products.get("my-space", "my-product")

Imports

All exceptions are importable from the top-level package:

from qarion import (
    QarionError,
    AuthenticationError,
    PermissionDeniedError,
    NotFoundError,
    ValidationError,
    ConflictError,
    ServerError,
    TimeoutError,
)