Original tutorialDocs reviewed

Handle Jev Python timeouts, retries and error states

A bounded call boundary and persistent task-state design.

Use caseConfigure bounded SDK retries, distinguish authentication, timeout and response validation errors, retain request IDs and persist task states for refresh and duplicate submissions.

Source · JevLog editorialIntermediate15 min

Start reading

Configure bounded SDK retries, distinguish authentication, timeout and response validation errors, retain request IDs and persist task states for refresh and duplicate submissions.

Source · JevLog editorial · Original guide

Source cover · TypeSafe AI

Source cover · TypeSafe AI

Published 2026-10-02 from current official docs with original exercises. No live service calls; source publication dates not established.

Problem

An endless progress indicator or HTTP failure treated as uncertainty prevents recovery. Calls need terminal states separating model uncertainty, transport failures and configuration errors.

Before you begin

Install typesafe-sdk and set TYPESAFE_API_KEY on the server. retry-scenarios.json is a checklist, not a service call.
Choose one primary retry layer and a total budget, rather than multiplying retries across layers.
Official docs
Official docs
Official docs

Original JevLog diagram, not a product screenshot or measured result.

Original JevLog diagram, not a product screenshot or measured result.

Steps

1. Classify failures before retrying

Fix credentials and permission for 401/403 and inputs for 400/422. Consider bounded retries for rate limits and temporary server errors. Invalid response structure is an error, never an invented classification.

2. Separate attempts, request timeout and budget

One retry means at most two attempts. RetryPolicy.timeout bounds the total retry budget; client timeout controls a request. These illustrative values require adjustment, and are not latency claims.

from typesafe_sdk import (TypeSafeClient, Choice, RetryPolicy, TypeSafeError,
 TypeSafeAPIError, TypeSafeAPITimeoutError, TypeSafeAPIResponseValidationError)

def classify(state):
 try:
  with TypeSafeClient(timeout=5.0, retry=RetryPolicy(max_retries=1,
    backoff_initial=0.5, backoff_max=1.0, timeout=12.0,
    respect_retry_after=True)) as client:
   result = client.system_one(state, {"category": Choice(
    instructions="Classify this report",
    criteria={"bug":"Software malfunction","other":"Other"})})
   return {"status":"succeeded","choice":result.choices["category"].choice}
 except TypeSafeAPITimeoutError:
  return {"status":"retryable_error","reason":"timeout"}
 except TypeSafeAPIResponseValidationError:
  return {"status":"invalid_response"}
 except TypeSafeAPIError as error:
  retryable = error.status in (408,429) or error.status >= 500
  return {"status":"retryable_error" if retryable else "request_error",
          "http_status":error.status,"request_id":error.request_id}
 except TypeSafeError:
  return {"status":"configuration_or_connection_error"}

3. Persist UI state with a job ID

Persist running and terminal states under a job ID. Button disabling handles only the current page; refresh reads stored state. Application request keys handle deduplication without assuming API idempotency.

4. Keep side effects outside retries

Put messaging, ticket creation and charging in a separate stage with uniqueness or explicitly supported idempotency. A timeout means an unknown result, not proof of no processing.

5. Record exhausted budgets and recovery

Log task, question version, elapsed time, status and request ID without secrets. Show an incomplete state and link retries to the prior job. This article makes no live call; verify SDK and rate limits with your account.

Practice sample: download retry-scenarios.json for local use; not a live run here.

Result and cautions