Timeouts and long-polling

GET /numbers/sms/wait, GET /emails/get-email and POST /captchas/resolve are long-polling endpoints. The request stays open until the result is ready, and the response is the result.

If what you are waiting for has already happened (an SMS or email that arrived before you asked), the response is immediate.

Bounding the wait

Send the X-Service-Timeout header with the longest you are willing to wait, in milliseconds. It must be a positive integer; anything else returns 400.

curl -G https://api.clearance.rest/emails/get-email \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
  -H "X-Service-Timeout: 45000" \
  --data-urlencode "email_account=test@domain.com"

Each service also has a ceiling that the header can lower but never raise:

Endpoint	Ceiling
GET /numbers/sms/wait	5 minutes
GET /emails/get-email	5 minutes
POST /captchas/resolve	10 minutes

Without the header, the wait lasts up to the ceiling.

What a timeout looks like

A wait that runs out is not an HTTP error. The response is 200, so check the body:

{ "success": false, "error": "timeout" }

For Captchas the body also carries the job details:

{ "jobId": "6f1c1a4e-2f0e-4c39-9d1b-3f7a7f8c2b10", "waitedMs": 45000, "error": "timeout" }

The SDKs turn this into a typed timeout error for you. See SDK errors.

Client-side limits

Many HTTP clients have their own default timeout, often 30 or 60 seconds. Set yours above the X-Service-Timeout you send, or the client will give up first. The SDKs do this automatically by adding a margin to the timeout you pass.

If your client disconnects, the server stops waiting on your behalf. For Captchas that only cancels providers that support cancellation; a solve that has already been paid for at the provider may still complete there.