error-handling.md

Error handling

Common errors

• NotAuthenticatedError
• TooManyRequestsError
• TooManyConcurrentRequestsError
• TooManyExecutionsError
• MaintenanceError
• AccessDeniedToGatewayError
• BadCredentialsError

Retry and backoff guidance

Use short, jittered delays for transient errors and re-authenticate on auth failures.

import asyncio

from pyoverkiz.auth.credentials import UsernamePasswordCredentials
from pyoverkiz.client import OverkizClient
from pyoverkiz.enums import Server
from pyoverkiz.exceptions import (
    NotAuthenticatedError,
    TooManyConcurrentRequestsError,
    TooManyRequestsError,
)


async def fetch_devices_with_retry() -> None:
    async with OverkizClient(
        server=Server.SOMFY_EUROPE,
        credentials=UsernamePasswordCredentials("you@example.com", "password"),
    ) as client:
        await client.login()
        for attempt in range(5):
            try:
                devices = await client.get_devices()
                print(devices)
                return
            except (TooManyRequestsError, TooManyConcurrentRequestsError):
                await asyncio.sleep(0.5 * (attempt + 1))
            except NotAuthenticatedError:
                await client.login()


asyncio.run(fetch_devices_with_retry())

SSL and local certificates

If you use local gateways with .local hostnames, you may need verify_ssl=False when a trusted certificate is not available.

Timeouts

For long-running operations, prefer shorter request timeouts with retries rather than a single long timeout.