Errors & retries

Catching errors

Every API and network error raises a typed TawaAPIError rather than returning an error-shaped result. A successful scan never needs an error check beyond your normal try/except.

from tawaguard import TawaGuard, TawaAPIError

try:
    client = TawaGuard("YOUR_API_KEY")
    result = client.analyze(user_input)
except TawaAPIError as err:
    print(err.message)     # error description
    print(err.status_code) # HTTP status code (or None for network errors)
    print(err.retryable)   # whether a retry could succeed

Automatic retries

Both the sync and async client retry transient failures automatically — up to 3 attempts by default, with exponential backoff and jitter between them:

• 429 (rate limited) — honors a Retry-After header when the server sends one, falls back to backoff otherwise.
• 5xx (server errors) — same backoff, no Retry-After expected.
• Network errors (connection failures, timeouts) — retried the same way.

Anything else — 4xx other than 429, or exhausting max_retries — raises immediately. retryable on the caught error tells you whether the SDK already gave up on a retryable class of error (all attempts exhausted) or the error was never retryable to begin with (e.g. a 401).

Tuning retries and timeouts

Both the sync and async client take max_retries/timeout at construction:

client = TawaGuard(
    "YOUR_API_KEY",
    max_retries=5,   # default: 3
    timeout=60.0,    # default: 30.0 seconds
)

See Configuration for the full option set, and the API Reference for the raw HTTP rate-limit contract (Retry-After, recommended backoff) this retry behavior is built on top of.