Recover hCaptcha jobs after timeouts and worker restarts
Persist task IDs, separate unknown submissions from rejected jobs, and resume lookups without creating duplicate paid tasks.
Record acceptance before doing the next operation
A worker can stop after the API accepts a job but before the rest of your application records it. Save the returned task ID as soon as creation succeeds, along with the operation that requested it. Do not wait until the token arrives to establish that relationship.
Your local record can use states such as submitting, accepted, completed, failed, and submission-unknown. These are application bookkeeping states, not replacements for the API’s queued and running statuses. Keep the remote snapshot separate from the local recovery decision.
Reconcile a known ID
When an accepted job is still pending, retrieve the same ID. When a worker restarts, load accepted jobs that lack a terminal observation and schedule their lookups. Confirm that the credentials used for recovery belong to the same account and can access the task.
| Local observation | Recovery action |
|---|---|
| Creation returned an ID | Persist it and retrieve the same job |
| Lookup timed out | Retry observation for that known ID |
| Creation timed out without an ID | Mark the submission outcome unknown |
| Job is failed | Handle the documented task error |
A repeated lookup observes existing work. A repeated creation requests new work. Build retry policies around that distinction instead of applying the same middleware to every HTTP method.
Keep uncertain submissions visible
A network timeout without a task ID does not prove the server rejected the request. Blindly resubmitting can incur another charge. Keep an incident or application record that lets an operator inspect the unknown attempt and decide the next step.
Do not invent an idempotency guarantee or a cancellation endpoint that the public API contract does not provide. If your own application assigns an operation ID, it can prevent duplicate local scheduling, but it does not by itself deduplicate remote POST requests.
Define an observation deadline separately from retention. A user-facing request might stop waiting while a background worker continues reconciliation. Keep sensitive payloads out of recovery logs; identifiers and failure stages are usually enough to investigate the lifecycle. The bounded queue guide covers scheduling, and unknown-outcome reporting explains how to measure unresolved attempts honestly.