Retry CAPTCHA Tasks Without Creating Duplicates

Reuse the same Idempotency-Key and request body after a timeout. Handle conflicts and preserve taskId beyond the replay window.

For authorized QA automation and browser integration. Use only on websites and workflows you have permission to test.

One logical task, one stable key

Persist an Idempotency-Key before POSTing a task. The key is 8–128 bytes and must stay attached to the exact same request body when retrying. Do not generate a fresh UUID inside a retry loop.

A timeout can hide a successful create

If the server accepted your request but the response was lost, submitting the same request with a new key can create another billable task. Replay the original key and body, then persist the returned taskId and switch to GET polling.

business operation -> persist key + exact JSON
POST -> network outcome unknown -> retry same key + same JSON
POST -> taskId available -> persist taskId -> GET only

What if HTTP 409 is returned?

IDEMPOTENCY_CONFLICT means the key has been used with a conflicting request. Compare the original type and payload before retrying. A different business operation needs its own key, but changing the key is not a safe workaround for an uncertain original operation.

Keep taskId longer than the replay window

The task idempotency record is retained for approximately 25 hours. Persist taskId in your business record for long-term lookup and deduplication; do not assume an old POST remains replayable forever. If no taskId was received and the replay window has elapsed, reconcile the outcome before creating another task.

Which failures can be retried?

Network errors and retryable 5xx can be retried within a budget using the original key and body. Respect Retry-After for limits. Correct invalid fields and permissions rather than replaying a broken request. See error handling and the API reference.

The Python and Node.js examples require a persisted key from the environment and support resuming by taskId.