NozleError.
NozleAuthenticationError before NozleValidationError if the branches need different handling because authentication errors are a validation subtype.
Safe API details
NozleAPIError exposes:
operation;status_code;response_details;request_id, theX-Request-Idresponse header (Core sends it, the Engine does not yet), orNone. Quote it when you contact support; andretry_after, the seconds from theRetry-Afterheader (a number or an HTTP date), orNone.
status_code is not always an HTTP error status. When track() resolves the subscription itself and the customer has no active subscription, or more than one, it raises NozleAPIError with status_code 200. The message gives the cause: no active subscription for customer '…' or has 2 active subscriptions; specify subscription_id. Do not treat 200 as success. See subscription resolution.
The transport redacts known secret, token, authorization, and key fields and replaces the active API key if it appears in a string response.
Retry behavior
By default the SDK does not retry, so a mutation is never replayed without application context. Setmax_retries (and optionally retry_delay) to retry network errors, timeouts, 429 and 5xx with backoff, or after NozleAPIError.retry_after seconds when the service sent Retry-After. Only requests that are safe to repeat are retried: reads, calls that carry an idempotency key (such as usage.track), event, cost event and customer writes, and the read-only usage check and transition preview. subscribe, checkout and other writes without a key are never retried.
- For idempotent Entity, credit-transfer, and usage mutations, retry with the same idempotency key and payload.
- For
track(), retry the same event with the same transaction ID. - Decide whether a read is safe to retry according to your request budget.
- Do not generate a new idempotency key after an uncertain outcome.
LLM wrapper warnings
LLM wrappers preserve successful provider responses when Nozle tracking fails. They emitNozleTrackingWarning instead of replacing the provider result.
The warning text names only the exception type, not the cause, for example Nozle tracking failed after a successful LLM response (NozleAPIError). Under python -W error, the SDK swallows the warning instead of raising it.