Erros da API solvethree: o que corrigir e quando tentar novamente

Trate as respostas HTTP sem sucesso antes de ler um payload de sucesso. Para POST /v1/tasks, 201 significa que uma nova tarefa foi criada; 200 significa que um reenvio idempotente retornou a tarefa existente. Nenhuma das respostas significa que a resolução terminou.

400 — corpo da requisição inválido

Compare o corpo enviado com os campos e requisitos documentados para o seu tipo de tarefa.

Experimente: Corrija os dados de entrada antes de enviar novamente. Reenviar um corpo inválido sem alterações não resolverá o problema. Use o contrato de criação de tarefas para verificar a requisição.

401 — chave de API inválida

Verifique se a requisição inclui Authorization: Bearer seguido de uma chave de API válida do espaço de trabalho.

Experimente: Adicione a chave ausente ou corrija a chave rejeitada. Mantenha-a no servidor em vez de expô-la no código do navegador.

402 — crédito insuficiente

Verifique o saldo de crédito do espaço de trabalho associado à chave de API.

Experimente: Adicione crédito a esse espaço de trabalho antes de tentar novamente. Não trate erros HTTP ou falhas de tarefas sem relação com o saldo como problemas de saldo.

403 — perfil do site inativo

Para reCAPTCHA, confirme que o site de destino tem um perfil ativo disponível para o seu espaço de trabalho.

Experimente: Configure o site de destino no console e confirme que o perfil está ativo. Informar um nome de host e uma ação na tarefa não cria um perfil. Essa resposta do gateway não é evidência de que o site de destino bloqueou você.

409 — conflito de ID de requisição

Verifique se o mesmo requestId já foi usado com dados de entrada de tarefa diferentes.

Experimente: Use os dados de entrada originais para recuperar a tarefa original. Se pretende criar uma tarefa diferente, atribua a ela um novo ID de requisição.

410 — resultado armazenado expirado

Verifique se você está consultando uma tarefa concluída cujo resultado armazenado não está mais retido.

Experimente: Pare de buscar esse resultado. Crie uma nova resolução se ainda precisar de uma. Esse status descreve a retenção de resultados da API, não o tempo de vida do token ou cookie de destino.

429 — limite de requisições atingido

Leia o valor de Retry-After efetivamente retornado na resposta.

Experimente: Aguarde conforme indicado antes de tentar novamente e reduza a taxa de requisições. Não continue consultando ou enviando requisições na mesma frequência enquanto estiver sob limitação.

502 — serviço de geração indisponível

Diferencie indisponibilidade do serviço de dados de entrada inválidos ou crédito insuficiente.

Experimente: Tente novamente mais tarde. Para outra tentativa da mesma requisição de criação, reutilize o ID de requisição e os dados de entrada da tarefa sem alterações.

HTTP 503 significa que a capacidade de geração está indisponível. Tente novamente mais tarde; para a mesma requisição de criação, reutilize o ID de requisição e os dados de entrada da tarefa sem alterações.

• pending ou solving: continue consultando periodicamente a tarefa existente; não crie uma substituta só porque ela ainda não está pronta.
• ready: pare de consultar e leia a solução.
• failed: pare de consultar e verifique errorCode e error.

{
  "id": "example_login_001",
  "status": "failed",
  "errorCode": "site-unreachable",
  "error": "target page did not respond"
}

Aqui, site-unreachable é um código de erro da tarefa, não um status HTTP. Verifique a URL de destino enviada e se a página responde antes de solicitar outra resolução. Mais consultas não reiniciarão essa tarefa com falha, e reenviar seu ID de requisição original retorna a tarefa existente em vez de iniciar uma substituta.

Um timeout de conexão não comprova que a criação da tarefa falhou. Use um requestId opcional antes da primeira tentativa de criação para poder recuperar a mesma tarefa lógica com segurança. Ele deve conter de 1–64 letras ASCII, números, sublinhados ou hífens.

1. 1.

   Se você tiver o ID da tarefa, consulte-a

   Use GET /v1/tasks/:id e trate a resposta HTTP antes de verificar o status da tarefa.

2. 2.

   Se a resposta de criação se perdeu, reenvie a requisição original

   Envie os mesmos dados de entrada da tarefa com o mesmo ID de requisição. O reenvio idempotente retorna a tarefa existente se ela tiver sido criada. Não altere os dados de entrada associados a esse ID.

3. 3.

   Crie uma substituta somente quando quiser iniciar outra resolução

   Um novo ID de requisição representa um novo trabalho, não a recuperação da requisição anterior. Use-o de forma deliberada — por exemplo, após investigar uma falha terminal e decidir tentar novamente.

Consulte recuperação por ID de requisição para saber como tratar reenvios, ou consultas periódicas e tempos limite quando a criação tiver sucesso, mas a tarefa ainda estiver em execução.