Gestiona las consultas periódicas de tareas CAPTCHA y los tiempos de espera

waitMs controla cuánto tiempo espera una solicitud de API por un resultado antes de responder. Es un parámetro de consulta de la URL, no un campo del JSON de la tarea. Los valores predeterminados de creación varían según el producto; las consultas GET tienen su propio límite.

Da al cliente HTTP tiempo suficiente para la espera solicitada al servidor más la sobrecarga de red. Un tiempo de espera del cliente inferior a la espera del servidor puede interrumpir la respuesta antes de que recibas el estado actual de la tarea.

El método solve de los SDK oficiales crea una sola vez y consulta hasta obtener un resultado listo o un error. Python ofrece timeout en segundos y poll_interval en segundos; Node.js ofrece timeoutMs y pollIntervalMs en milisegundos. La configuración documentada usa un plazo de resolución de tres minutos y un intervalo de consulta de un segundo.

Para un control directo, Python proporciona create_task y get_task; Node.js proporciona createTask y getTask. Sigue esta secuencia:

1. 1.

   Establece un plazo y crea una sola tarea

   Elige un plazo total antes de la creación. Conserva un requestId junto con los datos de entrada exactos de la tarea para poder recuperarla si se interrumpe la creación. Para evitar esperar durante la creación, selecciona explícitamente una espera de cero.

2. 2.

   Guarda el ID de tarea devuelto e inspecciona su estado

   La creación puede devolver ya un resultado final. Devuelve la solución si el estado es ready. Si es failed, inspecciona errorCode y error y detente; las resoluciones fallidas se reembolsan. Solo pending y solving requieren más consultas.

3. 3.

   Recupera la misma tarea mientras quede tiempo

   Usa GET /v1/tasks/:id, opcionalmente con una espera de consulta larga de hasta 15000 ms. Gestiona las respuestas HTTP no satisfactorias antes de leer un cuerpo de respuesta de éxito. Si la respuesta sigue indicando pending o solving, repite la consulta con el mismo ID, sin crear otra tarea.

4. 4.

   Detente al vencer el plazo

   Limita cada solicitud al tiempo restante, dejando margen para la sobrecarga de red. Cuando venza tu plazo, detén el bucle local y conserva el ID de tarea para recuperarla. No cambies el estado de la tarea a failed solo porque tu cliente haya dejado de esperar.

Esta solicitud recupera una tarea existente y permite una espera del servidor de 15 segundos y un tiempo de espera del cliente de 30 segundos. Asigna a TASK_ID el ID guardado y mantén SOLVETHREE_API_KEY en el servidor. Ninguno de estos tiempos de espera es un plazo total para un bucle 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"

Una respuesta HTTP satisfactoria puede contener una tarea que aún requiere consultas. pending y solving no son estados finales; solo ready contiene una solución utilizable. failed es un estado final e incluye errorCode y 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"
  }
}

La respuesta lista que se muestra aquí contiene un token de reCAPTCHA. Kasada devuelve cabeceras y TMPT devuelve un valor de cookie sin procesar en su lugar. Un resultado listo significa que se generó una solución, no que el destino posterior la aceptara. Si se rechaza un token de reCAPTCHA listo, pasa del diagnóstico de las consultas a comprobar el token enviado.

Un tiempo de espera de conexión agotado indica que el cliente no recibió una respuesta completa. No demuestra que la creación fallara. Antes de pagar por otra resolución, recupera la tarea que quizá ya hayas creado.

1. 1.

   Si tienes un ID de tarea, reanuda las consultas GET

   Recupera ese ID con un nuevo plazo local limitado. Que se agote el tiempo de espera de una solicitud GET no es motivo para enviar otra solicitud de creación.

2. 2.

   Si se interrumpió la creación, reutiliza su requestId

   Repite la solicitud de tarea idéntica con el mismo requestId para recuperar la tarea existente. Cambiar los datos de entrada de la tarea al reutilizar ese ID genera un conflicto. Consulta recuperación mediante ID de solicitud para conocer todas las condiciones.

Ambos SDK generan un requestId si se omite y nunca reintentan la creación automáticamente. Su SolvethreeError expone los ID de recuperación: request_id y task_id en Python, o requestId y taskId en JavaScript. Comprueba esos campos antes de decidir crear una nueva tarea lógica.

Una solicitud de consulta devuelve un error HTTP

Inspecciona el estado HTTP por separado del estado de la tarea. ApiError del SDK expone ese estado y cualquier demora de reintento.

Prueba esto: Para fallos temporales en las consultas, respeta Retry-After dentro del plazo total de resolución. Los campos del SDK son retry_after en segundos en Python y retryAfterMs en milisegundos en JavaScript.

La tarea devuelve failed

Lee errorCode y error; el SDK representa este caso como TaskFailedError.

Prueba esto: Deja de consultar esa tarea. Diagnostica la causa indicada antes de crear otra; no reintentes a ciegas los mismos datos de entrada no válidos ni supongas que el problema es el crédito.

La recuperación devuelve HTTP 410

El resultado almacenado ha caducado.

Prueba esto: Deja de reintentar la recuperación como si fuera un error temporal de consulta. Los resultados completados tienen un período de retención limitado y no son una caché permanente de soluciones.

Guardar una respuesta lista no prolonga la vigencia del token o de la cookie del destino.