Gerencie consultas periódicas e timeouts de tarefas CAPTCHA

waitMs controla por quanto tempo uma requisição à API aguarda um resultado antes de responder. Ele é um parâmetro de query da URL, não um campo no JSON da tarefa. Os padrões de criação variam por produto; as consultas GET têm seu próprio limite.

Dê ao cliente HTTP tempo suficiente para a espera solicitada ao servidor, mais o tempo adicional de rede. Um timeout do cliente menor que a espera do servidor pode interromper a resposta antes que você receba o estado atual da tarefa.

O método solve dos SDKs oficiais cria a tarefa uma única vez e faz consultas até obter um resultado pronto ou um erro. Python expõe timeout em segundos e poll_interval em segundos; Node.js expõe timeoutMs e pollIntervalMs em milissegundos. As configurações documentadas usam um prazo de três minutos para a resolução e um intervalo de um segundo entre consultas.

Para controle direto, Python fornece create_task e get_task; Node.js fornece createTask e getTask. Use esta sequência:

1. 1.

   Defina um prazo e crie uma tarefa

   Escolha um prazo total antes da criação. Guarde um requestId com os dados exatos da tarefa para recuperar uma criação interrompida. Para evitar a espera durante a criação, selecione explicitamente uma espera de zero.

2. 2.

   Salve o ID da tarefa retornado e inspecione seu status

   A criação já pode retornar um resultado terminal. Retorne a solução se o status for ready. Se for failed, inspecione errorCode e error e pare; resoluções que falham são reembolsadas. Apenas pending e solving exigem mais consultas.

3. 3.

   Consulte a mesma tarefa enquanto houver tempo

   Use GET /v1/tasks/:id, opcionalmente com uma espera de long polling de até 15000 ms. Trate as respostas HTTP que não indicam sucesso antes de ler um payload de sucesso. Se a resposta ainda indicar pending ou solving, repita a consulta com o mesmo ID — não crie outra tarefa.

4. 4.

   Pare ao atingir o prazo

   Limite cada requisição ao tempo restante, reservando uma margem para o tempo adicional de rede. Quando seu prazo expirar, pare o loop local e mantenha o ID da tarefa para recuperação. Não reclassifique a tarefa como falha só porque seu cliente parou de esperar.

Esta requisição consulta uma tarefa existente, permitindo uma espera de 15 segundos no servidor e um timeout de 30 segundos no cliente. Defina TASK_ID com o ID salvo e mantenha SOLVETHREE_API_KEY no servidor. Nenhum desses timeouts é um prazo total para um loop de consultas repetidas.

curl --fail-with-body --max-time 30 \
  "https://api.solvethree.com/v1/tasks/$TASK_ID?waitMs=15000" \
  -H "Authorization: Bearer $SOLVETHREE_API_KEY"

Uma resposta HTTP de sucesso pode conter uma tarefa que ainda precisa de consultas. pending e solving não são terminais; apenas ready contém uma solução utilizável. failed é terminal e inclui errorCode e error.

{
  "nonterminal": [
    {
      "id": "example-task",
      "status": "pending"
    },
    {
      "id": "example-task",
      "status": "solving"
    }
  ],
  "ready": {
    "id": "example-task",
    "status": "ready",
    "solution": {
      "token": "EXAMPLE_TOKEN",
      "userAgent": "EXAMPLE_USER_AGENT",
      "secChUa": "EXAMPLE_CLIENT_HINTS"
    }
  },
  "failed": {
    "id": "example-task",
    "status": "failed",
    "errorCode": "site-unreachable",
    "error": "target page did not respond"
  }
}

A resposta pronta mostrada aqui contém um token reCAPTCHA. Kasada retorna cabeçalhos, enquanto TMPT retorna um valor de cookie bruto. Um resultado pronto significa que uma solução foi gerada — não que o destino subsequente a aceitou. Se um token reCAPTCHA pronto for rejeitado, deixe o diagnóstico das consultas e passe à verificação do token enviado.

Um timeout de conexão informa que o cliente não recebeu uma resposta completa. Ele não comprova que a criação falhou. Antes de pagar por outra resolução, recupere a tarefa que você talvez já tenha criado.

1. 1.

   Se você tem um ID de tarefa, retome as consultas GET

   Consulte esse ID com um novo prazo local finito. Um GET que excedeu o tempo limite não é motivo para enviar outra requisição de criação.

2. 2.

   Se a criação foi interrompida, reutilize seu requestId

   Reenvie a requisição de tarefa idêntica com o mesmo requestId para recuperar a tarefa existente. Alterar os dados da tarefa ao reutilizar esse ID gera um conflito. Consulte recuperação por ID de requisição para ver o contrato completo.

Ambos os SDKs geram um requestId quando ele é omitido e nunca repetem automaticamente a criação. O SolvethreeError deles expõe IDs de recuperação: request_id e task_id em Python, ou requestId e taskId em JavaScript. Verifique esses campos antes de decidir criar uma nova tarefa lógica.

Uma requisição de consulta retorna um erro HTTP

Inspecione o status HTTP separadamente do status da tarefa. ApiError do SDK expõe esse status e qualquer intervalo de espera para nova tentativa.

Experimente: Para falhas temporárias nas consultas, respeite Retry-After dentro do prazo total de resolução. Os campos do SDK são retry_after em segundos no Python e retryAfterMs em milissegundos no JavaScript.

A tarefa retorna failed

Leia errorCode e error; o SDK representa isso como TaskFailedError.

Experimente: Pare de consultar essa tarefa. Diagnostique a causa informada antes de criar outra; não repita tentativas às cegas com os mesmos dados inválidos nem presuma que o problema seja saldo.

A consulta retorna HTTP 410

O resultado armazenado expirou.

Experimente: Pare de tentar consultar novamente como se fosse um erro temporário de consulta. Os resultados concluídos têm retenção limitada e não são um cache permanente de soluções.

Salvar uma resposta pronta não prolonga a validade do token ou cookie no destino.