Use hold and long polling for hCaptcha tasks
Choose server wait intervals and HTTP deadlines that reduce lookup traffic while keeping creation, pending work, and cancellation behavior explicit.
A wait interval is not a completion promise
The easycaptcha API accepts hold during task creation and lookup, allowing a request to wait up to 30 seconds for a state change or completion. If the wait ends while work is still queued or running, your integration must continue observing the same task.
Use a client HTTP timeout longer than the requested server interval, leaving room for the network and response processing. Setting both to exactly 30 seconds creates a race in which the client may stop waiting just as the server responds.
Decide where your application waits
A short user-facing request may submit work and return its ID to an application-owned background worker. A synchronous command-line operation may wait for the task itself. Neither choice changes the supported task states or cancels the work when local waiting stops.
For raw HTTP retrieval, a known task can be observed with a URL such as:
GET /v1/task/YOUR_TASK_ID?hold=30
Authorization: Bearer YOUR_API_KEYReplace the placeholder with the full returned task identifier. Do not try to generate an ID or drop its task_ prefix.
Know the SDK method boundary
The SDKs expose a creation request with hold. Their basic get_job or getJob methods perform a lookup; do not assume they accept an undocumented query option for server-side hold. Use the documented SDK signatures, or use the raw API when you specifically need a held lookup.
A polling loop should have a local deadline and a pause between observations. Record the task ID before starting the loop. Keep pending results visible rather than treating exhaustion of the loop as a definitive solver failure.
Test timeouts at both layers
Exercise a fast completion, a job still pending at the end of hold, a lookup transport error, and an uncertain creation response. Confirm the program does not create extra tasks in order to “keep waiting.”
Long polling can reduce request volume, but it also holds a local connection open. Account for that in your application’s HTTP server and connection pool. Compare polling and long polling, then use task recovery to preserve accepted work when a process or browser stops observing it.