Errors

New to the SDK? Getting started shows how to connect and use it.

DlthubError

Base for every error raised by the SDK.

Attributes

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

ApiError

Subclass of DlthubError.

The platform rejected the request or returned an unusable response.

BadRequest

Subclass of 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

Subclass of ApiError.

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

ServerError

Subclass of ApiError.

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

Conflict

Subclass of 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

Subclass of DlthubError.

The credential is missing, malformed, or rejected.

DataplaneTokenRejected

Subclass of 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

Subclass of DlthubError.

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

message says what was missing.

NotFound

Subclass of DlthubError.

The addressed resource does not exist.

Attributes

Name	Type	Description
kind	EntityKind	What was looked for.
ref	str | None	The id or name that was not found, or None when the call addressed no particular one.
code	str | None	Stable platform error code, when the response carried one.
status	int | None	HTTP status the platform returned, when known.
fields	tuple[FieldError, ...]	Per-field reasons, when the platform reported any.
client_update	ClientUpdate | None	As for DlthubError.

ScopeMissing

Subclass of 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

Subclass of 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

Subclass of TransportError.

The platform could not be reached.

TransportTimeout

Subclass of TransportError.

An upload or log stream exceeded its time limit.

Other requests have no client-side timeout.

UnboundEntity

Subclass of 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

Subclass of DlthubError.

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

ClientUpdate

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

Attributes

Name	Type	Description
installed	str	The version running here.
minimum	str	The lowest version the platform supports.

ClientUpdate.from_headers()

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

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

Arguments

Name	Type	Description
headers	Mapping[str, str]	The response headers, looked up case-insensitively.

Returns: ClientUpdate | None — The update, or None when the installed version is not below the advertised minimum, or the response advertised none.

FieldError

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

Attributes

Name	Type	Description
key	str | None	The field at fault, when the platform named one.
message	str	What is wrong with it.