Skip to content

Errors

The exception hierarchy and the normalized ErrorKind classification.

Exception hierarchy and error kinds (ADR-0009, as amended).

Every class maps 1:1 to an ErrorKind value (class minus Error, SCREAMING_SNAKE). ProviderError is the unclassified catch-all and hosts the one nested leaf, EmptySolutionError (ADR-0040).

Behavioral discipline enforced at call sites (not in these classes):

  • Wrapped causes always chain: raise ... from cause.
  • Wrong-provider routing raises TypeError pre-flight, no network (ADR-0045); there is no dedicated exception for it.
  • No SolveCancelledError (ADR-0016) and no UnknownTaskError (ADR-0050) — by construction.

ErrorKind

Bases: Enum

Classification of library errors (ADR-0009, as amended).

UnicaptchaError

Bases: Exception

Base of the library error hierarchy.

Carries the error kind and the verbatim provider response body (raw_response) when one exists.

NetworkError

Bases: UnicaptchaError

Transport-level failure (DNS, refused, TLS, timeout).

AuthenticationError

Bases: UnicaptchaError

The provider rejected the API key.

InsufficientBalanceError

Bases: UnicaptchaError

The provider reported insufficient balance.

UnsupportedChallengeError

Bases: UnicaptchaError

The provider does not support this operation for this captcha kind.

Raised for server-side task-type rejections and client-side pre-flight coverage gaps alike (ADR-0057). Never for wrong-provider routing (TypeError) or unknown task ids (TaskStatus.UNKNOWN).

InvalidChallengeError

Bases: UnicaptchaError

A challenge was invalid client-side (validation failure).

TaskTimeoutError

Bases: UnicaptchaError

The solve/wait budget was exhausted (ADR-0010).

RateLimitError

Bases: UnicaptchaError

Rate limiting exhausted the retry policy (ADR-0059).

ServiceBusyError

Bases: UnicaptchaError

Provider capacity: no workers free (ADR-0059 amendment).

NoSolutionError

Bases: UnicaptchaError

Workers could not solve the captcha; no auto-resubmit (ADR-0029).

InvalidConfigError

Bases: UnicaptchaError

A configuration value was explicitly set to an invalid value.

None is always valid ("unspecified", ADR-0043); only explicit bad values raise (ADR-0042).

ClientClosedError

Bases: UnicaptchaError

An operation was attempted on a closed client (ADR-0033).

NoCaptchaDetectedError

Bases: UnicaptchaError

Auto-solve found no supported captcha in the page (ADR-0077).

ProviderError

Bases: UnicaptchaError

Unclassified provider error.

Also raised for malformed responses (HTTP 200, unparseable or wrong-shape body) with the parse failure chained as __cause__ and raw_response preserved (ADR-0040, ADR-0058).

EmptySolutionError

Bases: ProviderError

A "solved" response whose solution payload was empty (ADR-0040).

Subclass of ProviderError with its own kind: empty answers are typically transient worker failures and may be retried/rerouted, unlike generic garbage.

error_from_kind 

error_from_kind(kind, message, raw_response=b'')

Construct the exception leaf for an ErrorKind (provider mapping).

Public so third-party adapters can raise mapped provider errors without touching unicaptcha._internal (ADR-0041 boundary).