SDK errors

Every failed call throws a typed error. The SDKs never return an ambiguous value such as null or an empty code, so if a call returns, you have the result.

There are four kinds, all sharing one base class:

Kind	When	Extra data
Timeout	The server or client deadline passed and what you waited for never arrived.	waitedMs, jobId
Provider	The external provider (a captcha solver, Twilio, Hero SMS) returned an error or could not solve.	provider, providerCode
NoResult	The request worked, but there is no value to give you: no code could be extracted, or no token came back.	none
Request	Network failure, HTTP 4xx/5xx, an invalid parameter, or you cancelled.	status

Every error also carries service (captchas, emails or numbers) and data (the raw response body).

Node.js

Class	Kind
ChallengeError	Base class of all the others.
ChallengeTimeoutError	Timeout.
ChallengeProviderError	Provider.
ChallengeNoResultError	NoResult.
ChallengeRequestError	Request.

const {
  emails,
  ChallengeError, ChallengeTimeoutError, ChallengeNoResultError,
} = require('@clearance-rest/sdk');

try {
  const email = await emails.wait({ emailAccount: 'test@example.com', codeRegex: '\\d{6}', timeout: 5000 });
  use(email.code);
} catch (err) {
  if (err instanceof ChallengeTimeoutError)       handleTimeout(err.waitedMs);
  else if (err instanceof ChallengeNoResultError) handleNoCode();
  else if (err instanceof ChallengeError)         handleServiceError(err);
  else throw err;
}

PHP

All in the ClearanceRest\Exceptions namespace.

Class	Kind	Getters
ChallengeException	Base class of all the others.	getService(), getData()
ChallengeTimeoutException	Timeout.	getWaitedMs(), getJobId()
ChallengeProviderException	Provider.	getProvider(), getProviderCode()
ChallengeNoResultException	NoResult.	none
ChallengeRequestException	Request.	getStatus()

use ClearanceRest\Exceptions\{ChallengeException, ChallengeTimeoutException, ChallengeNoResultException};

try {
    $email = $client->emails->wait(emailAccount: 'test@example.com', codeRegex: '\d{6}', timeout: 5_000);
    use($email['code']);
} catch (ChallengeTimeoutException $e) {
    handleTimeout($e->getWaitedMs());
} catch (ChallengeNoResultException $e) {
    handleNoCode();
} catch (ChallengeException $e) {
    handleServiceError($e);
}

How API responses map to errors

Response	Error
200 with error: "timeout", or the client deadline passing	Timeout
A solver reports it could not solve (code: "ERROR_…", status: "failed")	Provider
200 but no token, or code_regex matched nothing	NoResult
400, 401, 404, 502, network failure, cancellation	Request

See Responses and errors for the underlying API behaviour.