---
title: Errors
description: Errors in the dltHub Runtime Python SDK (dlthub_sdk)
keywords: [dlthub, runtime, python sdk, dlthub_sdk, api]
---
# Errors

<!-- generated from dlthub-client 0.28.8a3, do not edit -->

New to the SDK? [Getting started](getting-started.md) shows how to connect and use it.

## `DlthubError` {#dlthuberror}

Base for every error raised by the SDK.

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `message` | <code>str</code> | Human-readable description. |
| `code` | <code>str &#124; None</code> | Stable platform error code, when the response carried one. Branch on this; `message` is prose and may change between releases. |
| `status` | <code>int &#124; None</code> | HTTP status the platform returned, when known. |
| `fields` | <code>tuple[<a href="#fielderror">FieldError</a>, ...]</code> | Per-field reasons, when the platform reported any. |
| `client_update` | <code><a href="#clientupdate">ClientUpdate</a> &#124; None</code> | Set when the failing response advertised a minimum client version above the installed one, a likely cause of the failure. |

## `ApiError` {#apierror}

Subclass of [`DlthubError`](#dlthuberror).

The platform rejected the request or returned an unusable response.

## `BadRequest` {#badrequest}

Subclass of [`ApiError`](#apierror).

The request itself was rejected. Retrying it unchanged will fail again.

`message` says why, `code` names the reason when the platform gave one, and
`fields` carries the per-field reasons when the platform named any. Also
raised before sending when an argument cannot form a request, e.g. an id
that is not a uuid; `status` is then `None`.

## `InvalidResponse` {#invalidresponse}

Subclass of [`ApiError`](#apierror).

A response did not parse, or broke an invariant the SDK depends on.

## `ServerError` {#servererror}

Subclass of [`ApiError`](#apierror).

The platform failed to handle the request. Retrying may succeed.

## `Conflict` {#conflict}

Subclass of [`DlthubError`](#dlthuberror).

The current state does not allow the call, e.g. the workspace is archived.

`code` names the reason when the platform gave one (`workspace_archived`,
`upstream_not_fresh`, ...) and `message` describes it. The set of reasons grows
with the platform, so branch on `code` rather than on this class alone.

## `NotAuthenticated` {#notauthenticated}

Subclass of [`DlthubError`](#dlthuberror).

The credential is missing, malformed, or rejected.

## `DataplaneTokenRejected` {#dataplanetokenrejected}

Subclass of [`NotAuthenticated`](#notauthenticated).

The data plane rejected the short-lived token the platform issued for it.

Your own credential was accepted (it obtained that token), so renewing or
replacing it will not help. For regular calls the SDK has already fetched a
fresh token and retried once; uploads are not retried.

## `NotAuthorized` {#notauthorized}

Subclass of [`DlthubError`](#dlthuberror).

The caller is authenticated but lacks the access the call needs.

`message` says what was missing.

## `NotFound` {#notfound}

Subclass of [`DlthubError`](#dlthuberror).

The addressed resource does not exist.

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `kind` | <code>EntityKind</code> | What was looked for. |
| `ref` | <code>str &#124; None</code> | The id or name that was not found, or `None` when the call addressed no particular one. |
| `code` | <code>str &#124; None</code> | Stable platform error code, when the response carried one. |
| `status` | <code>int &#124; None</code> | HTTP status the platform returned, when known. |
| `fields` | <code>tuple[<a href="#fielderror">FieldError</a>, ...]</code> | Per-field reasons, when the platform reported any. |
| `client_update` | <code><a href="#clientupdate">ClientUpdate</a> &#124; None</code> | As for [`DlthubError`](#dlthuberror). |

## `ScopeMissing` {#scopemissing}

Subclass of [`DlthubError`](#dlthuberror).

The call needs an organization or workspace that was not given.

For example, `runtime.workspaces.list()` without `organization_id` at
connect time or as an argument.

## `TransportError` {#transporterror}

Subclass of [`DlthubError`](#dlthuberror).

The request never produced a response.

Nothing was applied platform-side only if the request never arrived, which
this error cannot distinguish — treat a mutation as of unknown outcome.

## `ConnectionFailed` {#connectionfailed}

Subclass of [`TransportError`](#transporterror).

The platform could not be reached.

## `TransportTimeout` {#transporttimeout}

Subclass of [`TransportError`](#transporterror).

An upload or log stream exceeded its time limit.

Other requests have no client-side timeout.

## `UnboundEntity` {#unboundentity}

Subclass of [`DlthubError`](#dlthuberror).

The object was constructed directly, so it cannot call the platform.

Only objects returned by the SDK can. Also an `AttributeError`, so `hasattr`
keeps working.

## `WaitTimeout` {#waittimeout}

Subclass of [`DlthubError`](#dlthuberror).

What was awaited had not settled before the deadline. Nothing failed.

## `ClientUpdate` {#clientupdate}

The platform requires a newer `dlthub-client` than the one installed.

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `installed` | <code>str</code> | The version running here. |
| `minimum` | <code>str</code> | The lowest version the platform supports. |

### `ClientUpdate.from_headers()` {#clientupdate-from_headers}

```python
from_headers(headers: Mapping[str, str]) -> ClientUpdate | None
```

Read the platform's minimum client version off one response.

**Arguments**

| Name | Type | Description |
| --- | --- | --- |
| `headers` | <code>Mapping[str, str]</code> | The response headers, looked up case-insensitively. |

**Returns:** <code><a href="#clientupdate">ClientUpdate</a> &#124; None</code> — The update, or `None` when the installed version is not below the advertised minimum, or the response advertised none.

## `FieldError` {#fielderror}

One reason the platform rejected a request, as it reported it.

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `key` | <code>str &#124; None</code> | The field at fault, when the platform named one. |
| `message` | <code>str</code> | What is wrong with it. |