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.