# Exceptions

Handle TypeSafe API errors, rate limits, connection failures, and timeouts.

## Base exception

## typesafe_sdk.TypeSafeError

Bases: [Exception](https://docs.python.org/3/builtins/exceptions.html#Exception)

Base exception for SDK failures.

## HTTP errors

## typesafe_sdk.TypeSafeAPIError

Bases: [TypeSafeError](/sdk/python/api/exceptions#typesafe_sdk.TypeSafeError)

An unsuccessful HTTP response with its body and request metadata.

### typesafe_sdk.TypeSafeAPIError.status

`instance-attribute`

```python theme={null}
status = status
```

HTTP response status code.

### typesafe_sdk.TypeSafeAPIError.body

`instance-attribute`

```python theme={null}
body = body
```

The server's JSON error body, plain response text, or `None` for an empty body.

### typesafe_sdk.TypeSafeAPIError.headers

`instance-attribute`

```python theme={null}
headers = headers
```

HTTP response headers.

### typesafe_sdk.TypeSafeAPIError.endpoint

`instance-attribute`

```python theme={null}
endpoint = endpoint
```

The request method and URL, without credentials, query parameters, or fragment, when available.

### typesafe_sdk.TypeSafeAPIError.request_id

`property`

<SdkSignature>
  <span className="n">
    {"request_id"}
  </span>

<span className="p">
    {":"}
  </span>

{" "}

<span className="n">
    <a href="https://docs.python.org/3/builtins/stdtypes.html#str">{
      "str"}
    </a>
  </span>

{" "}

<span className="o">
    {"|"}
  </span>

{" "}

<span className="kc">
    {"None"}
  </span>

{"\n"}
</SdkSignature>

The `x-typesafe-request-id` response header, or `None` if absent.

## typesafe_sdk.TypeSafeBadRequestError

Bases: [TypeSafeAPIError](/sdk/python/api/exceptions#typesafe_sdk.TypeSafeAPIError)

The request was invalid (400).

## typesafe_sdk.TypeSafeAuthenticationError

Bases: [TypeSafeAPIError](/sdk/python/api/exceptions#typesafe_sdk.TypeSafeAPIError)

Authentication failed (401).

## typesafe_sdk.TypeSafePermissionDeniedError

Bases: [TypeSafeAPIError](/sdk/python/api/exceptions#typesafe_sdk.TypeSafeAPIError)

Access was denied (403).

## typesafe_sdk.TypeSafeNotFoundError

Bases: [TypeSafeAPIError](/sdk/python/api/exceptions#typesafe_sdk.TypeSafeAPIError)

The resource was not found (404).

## typesafe_sdk.TypeSafeUnprocessableEntityError

Bases: [TypeSafeAPIError](/sdk/python/api/exceptions#typesafe_sdk.TypeSafeAPIError)

The request failed server validation (422).

## typesafe_sdk.TypeSafeRateLimitError

Bases: [TypeSafeAPIError](/sdk/python/api/exceptions#typesafe_sdk.TypeSafeAPIError)

The rate limit was exceeded (429).

### typesafe_sdk.TypeSafeRateLimitError.retry_after_ms

`instance-attribute`

```python theme={null}
retry_after_ms = parse_retry_after(headers)
```

The server's requested wait in milliseconds, or `None` if unavailable.

## typesafe_sdk.TypeSafeInternalServerError

Bases: [TypeSafeAPIError](/sdk/python/api/exceptions#typesafe_sdk.TypeSafeAPIError)

The server failed to process the request (5xx).

## Connection errors

## typesafe_sdk.TypeSafeAPIConnectionError

Bases: [TypeSafeError](/sdk/python/api/exceptions#typesafe_sdk.TypeSafeError), [ConnectionError](https://docs.python.org/3/builtins/exceptions.html#ConnectionError)

A request failed without an HTTP response.

## typesafe_sdk.TypeSafeAPITimeoutError

Bases: [TypeSafeAPIConnectionError](/sdk/python/api/exceptions#typesafe_sdk.TypeSafeAPIConnectionError), [TimeoutError](https://docs.python.org/3/builtins/exceptions.html#TimeoutError)

A request exceeded its configured timeout.

### typesafe_sdk.TypeSafeAPITimeoutError.timeout

`instance-attribute`

```python theme={null}
timeout = timeout
```

The timeout setting used for the request, in seconds or as an `httpx2.Timeout`.

## Response validation

## typesafe_sdk.TypeSafeAPIResponseValidationError

Bases: [TypeSafeAPIError](/sdk/python/api/exceptions#typesafe_sdk.TypeSafeAPIError)

A successful HTTP response whose body was missing or structurally invalid required data.

### typesafe_sdk.TypeSafeAPIResponseValidationError.field_path

`instance-attribute`

```python theme={null}
field_path = field_path
```

Dotted path to the offending field, such as `answers.tone.confidence`.

### typesafe_sdk.TypeSafeAPIResponseValidationError.args

`instance-attribute`

```python theme={null}
args = (
    status,
    body,
    headers,
    field_path,
    endpoint,
)
```