Configuration.md

Configuration and errors

Use one client per application task or worker lifetime and close it with with or async with. Both clients accept VATLY_API_KEY or an explicit server-side key.

from vatly import RequestOptions, VatlyClient


def example():
    with VatlyClient(timeout=20, max_retries=2) as client:
        return client.customers.get("customer_example", options=RequestOptions(timeout=5))

Option	Meaning
api_key	Explicit key; otherwise read VATLY_API_KEY
timeout	HTTP timeout in seconds; request options can override it
max_retries	Automatic retry budget for eligible failures
base_url	HTTP(S) endpoint without query/fragment; use HTTPS for real credentials
RequestOptions.idempotency_key	Stable business key shared across caller retries
RequestOptions.headers	Additional request headers

Retryable failures include connection/timeouts, rate limits and eligible server errors. Mutations receive an automatic key for internal retries; persist your own key when retrying across application calls. A timeout can leave the remote outcome unknown. Never assume it means a purchase or refund did not happen.

Handle a missing resource

from vatly import VatlyClient, VatlyNotFoundError


def example(client: VatlyClient):
    try:
        return client.customers.get("customer_missing")
    except VatlyNotFoundError:
        return None

Catch VatlyError for all SDK errors. API errors expose status, body, method, URL and request ID where supplied; connection and timeout errors retain their httpx cause and request context. Avoid logging credentials or full response bodies, which can contain personal data. Invalid resource responses raise VatlyApiError rather than silently returning None.

API reference · Pagination examples