What does an API error carry?

TypeSafeAPIError carries status, body, headers, a credential-free endpoint, and the x-typesafe-request-id header. Status classes cover 400, 401, 403, 404, 422, 429, and 5xx.

How do I catch timeouts or bad response bodies?

TypeSafeAPITimeoutError subclasses TypeSafeAPIConnectionError for failed requests with no HTTP response, and TypeSafeAPIResponseValidationError covers a 2xx body that failed the response model, exposing a dotted field_path.

What is the base exception?

TypeSafeError, which subclasses Exception. Every SDK failure descends from it: HTTP failures through TypeSafeAPIError and connection problems through TypeSafeAPIConnectionError.

How do I read a rate-limit wait hint?

TypeSafeRateLimitError exposes retry_after_ms, parsed from the Retry-After headers, or None when the server did not send one. It is the class for a 429 response.

What does the endpoint recorded on an error look like?

The request method and URL without credentials, query parameters, or fragment, when available. request_id reads the x-typesafe-request-id response header and is None if absent.

What is in a response validation error?

TypeSafeAPIResponseValidationError marks a 2xx body that was missing or structurally invalid required data, and exposes a dotted field_path like answers.tone.confidence pointing at the offending field.

What is captured in the exception args?

For response validation errors the args tuple is status, body, headers, field_path, and endpoint. Timeout errors instead carry the timeout setting in seconds or as an httpx2.Timeout.

OfficialJev Repos & SDKs

Python SDK Exceptions

The Python SDK error hierarchy: HTTP status classes, rate-limit wait hints, connection and timeout errors, and response-body validation failures.

See highlights

Open docs.typesafe.ai

Format: Docs
Published by: TypeSafe AI
Last verified: Oct 2026

Tagsofficial docs sdk python retries

Works forJev for Classification

Used inJev for Software & DevTools

Languages: Python

Highlights

TypeSafeAPIError carries status, body, headers, a credential-free endpoint, and x-typesafe-request-id.
Status classes cover 400, 401, 403, 404, 422, 429, and 5xx. RateLimitError exposes retry_after_ms.
TypeSafeAPIConnectionError is a failed request with no HTTP response. TypeSafeAPITimeoutError subclasses it.
TypeSafeAPIResponseValidationError is a 2xx body that failed the response model, with a dotted field_path.

Watch out

A reference page. Retry behavior for 429 and 5xx lives on the RetryPolicy page.

Questions about this entry

Short answers drawn from the linked project or page.

Related terms

Glossary definitions related to this entry.

Client SDK

More Jev resources like this

Python SDK Retries

RetryPolicy for the Python SDK: attempt count, exponential backoff with jitter, which HTTP statuses retry, and a total time budget.