Skip to content

Errors and warnings

Every non-2xx answer becomes one of these exceptions, carrying the HTTP status, the server's message and the parsed body. All of them derive from WitanError, so one except WitanError catches everything the SDK raises.

Typed errors. Every non-2xx answer from WITAN becomes one of these, carrying the HTTP status, the server's error message and the raw JSON body.

WitanError

WitanError(message: str, *, status: int | None = None, code: str | None = None, body: Any = None)

Bases: Exception

Base class for every error raised by the SDK.

ValidationError

ValidationError(message: str, *, status: int | None = None, code: str | None = None, body: Any = None)

Bases: WitanError

400 — the request body or query did not pass the server's schema.

AuthError

AuthError(message: str, *, status: int | None = None, code: str | None = None, body: Any = None)

Bases: WitanError

401/403 — missing, malformed or unauthorized API key.

PaymentRequiredError

PaymentRequiredError(message: str, *, status: int | None = None, code: str | None = None, body: Any = None)

Bases: WitanError

402 — the resource is paid; use buy() (needs the x402 extra) or a wallet.

NotFoundError

NotFoundError(message: str, *, status: int | None = None, code: str | None = None, body: Any = None)

Bases: WitanError

404 — no such unit, project, contribution or topic.

ConflictError

ConflictError(message: str, *, status: int | None = None, code: str | None = None, body: Any = None)

Bases: WitanError

409 — e.g. a revision is already pending for this lineage.

AlreadyCovered

AlreadyCovered(message: str, *, status: int | None = None, code: str | None = None, body: Any = None)

Bases: ConflictError

409 from an x402 dataset purchase — the paying wallet already has this version through the update period of an earlier purchase, and nothing was charged. Get it with redeliver(err.transaction, version=err.version) (projects.pull_paid does that by itself).

NotCovered

NotCovered(message: str, *, status: int | None = None, code: str | None = None, body: Any = None)

Bases: AuthError

403 from redeliver(..., version=...) — the version asked for is not part of that purchase (an earlier one, or one published after its update period ended). Nothing was charged; buy is the pay route that sells it.

RateLimitError

RateLimitError(message: str, *, status: int | None = None, code: str | None = None, body: Any = None)

Bases: WitanError

429 — slow down; limits are per key and per IP.

ServerError

ServerError(message: str, *, status: int | None = None, code: str | None = None, body: Any = None)

Bases: WitanError

5xx — WITAN failed; safe to retry after a moment.

RightsConfirmationRequired

RightsConfirmationRequired(message: str, *, status: int | None = None, code: str | None = None, body: Any = None)

Bases: WitanError

428 — a unit derived from sources: read statement; if it is true, send the same call again with rights_confirmation=err.token (it expires at expires_at, about an hour). Nothing was submitted and no validation was used.

WaitTimeout

WaitTimeout(message: str, *, status: int | None = None, code: str | None = None, body: Any = None)

Bases: WitanError

A wait* helper gave up before the pipeline reached a terminal state.

brief

brief(text: Any) -> str | None

A readable error message: a proxy's HTML page (a 502, Cloudflare's 530) is not one.

raise_for

raise_for(response: Response) -> None

Turn an httpx error response into the matching WitanError.

SignatureError

SignatureError(message: str, *, status: int | None = None, code: str | None = None, body: Any = None)

Bases: WitanError

A manifest's signature is missing where required, untrusted, or does not match.

WitanDeprecationWarning

Bases: FutureWarning

A route this SDK called is deprecated on the server.

A FutureWarning, so Python shows it by default. Silence it with warnings.simplefilter("ignore", WitanDeprecationWarning) or fail on it in CI with warnings.simplefilter("error", WitanDeprecationWarning).