Error Handling

The SDK raises two expected exception types. Always handle both when performing write operations.

ValidationException

Raised for client-side failures — for example, when required fields or relationships are missing, or variant constraints are violated. The errors attribute is a list of ErrorEntry objects, each with a field and message property:

from cacholong_sdk import ValidationException

try:
    await ctrl.store(model)
except ValidationException as e:
    print(e.message)
    for entry in e.errors:
        print(f"  {entry.field}: {entry.message}")

DocumentError

Raised for API-side failures — a non-2xx HTTP response from the server (e.g., 404 Not Found, 422 Unprocessable Entity):

from cacholong_sdk import DocumentError

try:
    zone = await ctrl.fetch("NONEXISTENT-UUID")
except DocumentError as e:
    print(f"API error: {e}")

Full catch-all pattern

import asyncio
from cacholong_sdk import connection, DnsZone, ValidationException, DocumentError

async def main():
    async with connection("https://api.cacholong.eu/api/v1/", "YOUR-API-KEY") as api:
        ctrl = DnsZone(api)
        try:
            zone = await ctrl.fetch("ZONE-UUID")
            print(zone["domain"])
        except ValidationException as e:
            print(f"Validation error: {e.message}")
            for entry in e.errors:
                print(f"  {entry.field}: {entry.message}")
        except DocumentError as e:
            print(f"API error: {e}")
        except Exception as e:
            print(f"Unexpected error: {e}")

asyncio.run(main())