Errores de la API de solvethree: qué corregir y cuándo reintentar

Gestiona las respuestas HTTP no satisfactorias antes de leer el contenido de una respuesta satisfactoria. Para POST /v1/tasks, 201 significa que se ha creado una nueva tarea; 200 significa que un reenvío idempotente ha devuelto la tarea existente. Ninguna de las dos respuestas significa que la resolución haya terminado.

400 — cuerpo de solicitud no válido

Compara el cuerpo enviado con los campos y requisitos documentados para tu tipo de tarea.

Prueba esto: Corrige los datos de entrada antes de volver a enviarlos. Reintentar con un cuerpo no válido sin modificarlo no solucionará el problema. Usa el contrato de creación de tareas para comprobar la solicitud.

401 — clave de API no válida

Comprueba que la solicitud incluya Authorization: Bearer seguido de una clave de API válida del espacio de trabajo.

Prueba esto: Añade la clave que falta o corrige la clave rechazada. Mantenla en el servidor en lugar de exponerla en el código del navegador.

402 — saldo insuficiente

Comprueba el saldo del espacio de trabajo asociado a la clave de API.

Prueba esto: Añade saldo a ese espacio de trabajo antes de volver a intentarlo. No trates los errores HTTP no relacionados ni los fallos de tareas como problemas de saldo.

403 — perfil de sitio inactivo

Para reCAPTCHA, confirma que el sitio de destino tenga un perfil activo disponible para tu espacio de trabajo.

Prueba esto: Configura el sitio de destino en la consola y confirma que el perfil esté activo. Proporcionar un nombre de host y una acción en la tarea no crea un perfil. Esta respuesta de la pasarela no demuestra que el sitio web de destino te haya bloqueado.

409 — conflicto de ID de solicitud

Comprueba si el mismo requestId se ha utilizado anteriormente con otros datos de entrada de tarea.

Prueba esto: Usa los datos de entrada originales para recuperar la tarea original. Si quieres crear una tarea distinta, asígnale un nuevo ID de solicitud.

410 — resultado almacenado caducado

Comprueba si estás intentando obtener una tarea completada cuyo resultado almacenado ya no se conserva.

Prueba esto: Deja de solicitar ese resultado. Crea una nueva resolución si aún la necesitas. Este estado describe la conservación de resultados de la API, no la duración del token o de la cookie del sitio de destino.

429 — límite de solicitudes alcanzado

Lee el valor de Retry-After recibido en la respuesta.

Prueba esto: Espera el tiempo indicado antes de volver a intentarlo y reduce la frecuencia de las solicitudes. No sigas consultando ni enviando solicitudes a la misma frecuencia mientras se aplique la limitación.

502 — servicio de generación no disponible

Distingue la falta de disponibilidad del servicio de los datos de entrada no válidos o el saldo insuficiente.

Prueba esto: Vuelve a intentarlo más tarde. Para repetir la misma solicitud de creación, reutiliza su ID de solicitud y los datos de entrada de la tarea sin cambios.

HTTP 503 significa que no hay capacidad de generación disponible. Vuelve a intentarlo más tarde; para la misma solicitud de creación, reutiliza su ID de solicitud y los datos de entrada de la tarea sin cambios.

• pending o solving: sigue consultando periódicamente la tarea existente; no crees otra para sustituirla solo porque aún no esté lista.
• ready: deja de consultar y lee la solución.
• failed: deja de consultar e inspecciona errorCode y error.

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

Aquí, site-unreachable es un código de error de tarea, no un estado HTTP. Comprueba la URL de destino enviada y si la página responde antes de solicitar otra resolución. Más consultas no reiniciarán esta tarea fallida, y volver a enviar su ID de solicitud original devuelve la tarea existente en lugar de iniciar otra para sustituirla.

Un tiempo de espera de conexión agotado no demuestra que la creación de la tarea haya fallado. Usa un requestId opcional antes del primer intento de creación para poder recuperar de forma segura la misma tarea lógica. Debe contener entre 1–64 letras ASCII, números, guiones bajos o guiones.

1. 1.

   Si tienes el ID de tarea, obtén la tarea

   Usa GET /v1/tasks/:id y gestiona la respuesta HTTP antes de comprobar el estado de la tarea.

2. 2.

   Si se ha perdido la respuesta de creación, vuelve a enviar la solicitud original

   Envía los mismos datos de entrada de la tarea con el mismo ID de solicitud. El reenvío idempotente devuelve la tarea existente si se ha creado. No cambies los datos de entrada asociados a ese ID.

3. 3.

   Crea una tarea de sustitución solo cuando quieras iniciar otra resolución

   Un nuevo ID de solicitud representa trabajo nuevo, no la recuperación de la solicitud anterior. Úsalo deliberadamente; por ejemplo, después de investigar un fallo terminal y decidir volver a intentarlo.

Consulta recuperación mediante ID de solicitud para gestionar los reenvíos, o consultas periódicas y tiempos de espera cuando la creación haya tenido éxito pero la tarea siga en curso.