Polling & safe retries
Follow a task to completion without creating duplicate work.
Understand the task states
submitting means the task is being submitted; processing means it is waiting for a solution. Continue waiting for these states. ready means the answer is available in solution. failed means solving has ended without an answer.
Treat ready and failed as terminal states: stop polling. Check the task status even if the HTTP response is successful. A provider failure can be returned inside a task with HTTP 201 or 200.
Fetch a task
GET /captcha/tasks/{id} returns the task belonging to your account. Use the saved task ID. A saved task can also be located using the UUID v4 idempotency key supplied when creating it.
Poll at intervals of 5 to 10 seconds. There is a shared limit of 60 requests per minute per account, including all keys, task creation and polling. Schedule parallel workers together rather than letting every worker consume the full allowance.
curl "https://www.scrapingbuddy.com/api/v1/captcha/tasks/TASK_ID" \
-H "Authorization: Bearer $SCRAPINGBUDDY_API_KEY"Handle a client timeout
Use a finite waiting window. Our code examples wait approximately 3 minutes, but this is a client decision, not a solving-time guarantee or server cancellation.
If you stop waiting, save the task ID and resume GET polling later. Do not automatically create a replacement task. If creation timed out before returning an ID, check Usage or contact support with your request ID.
Use one request ID per task
Generate a UUID v4 before creating a new task and retain it with the request. Repeated POSTs can return an already saved task for that ID.
The same key and normalized input return the saved task without another submission or charge, including concurrent requests. A different body with the same key returns 409. If provider submission is unconfirmed, contact support with the task ID; do not create a replacement.
Back off after HTTP 429
Read the Retry-After response header and wait before resuming GET polling. The current header value is 60 seconds. Reduce concurrency if rate limiting continues.
The sample clients stop and report HTTP errors rather than automatically retrying creation. Add bounded GET retry handling in your application when you need automatic recovery.