Problemas comunes

Soluciones a los problemas más comunes al usar la API de FourA.

Contenido vacío o incompleto

Síntoma: La API devuelve un estado 200, pero el campo data está vacío o no contiene el contenido esperado.

Causa: La página de destino utiliza JavaScript para renderizar contenido después de la carga inicial de la página.

Solución: Cambia del endpoint simple al endpoint de browser. Usa checkText para verificar que el contenido haya cargado:

curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'

Nota: el endpoint de browser devuelve el contenido en el campo body (no en data).

Páginas 403 Forbidden o de verificación

Síntoma: La API devuelve HTML que contiene una página de verificación o una página de acceso denegado.

Causa: El sitio de destino detectó la request como automatizada y la bloqueó.

Solución: Usa el endpoint de proxy para la rotación automática de IP:

curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 5,
    "request": {
      "method": "GET",
      "url": "https://example.com/prices",
      "unblocker": true
    }
  }'

Si el problema persiste, aumenta maxTries para darle a la rotación de proxy más intentos.

Un error 403 devuelto por el destino llega como HTTP 200 con status: 403 dentro del cuerpo. Un error 403 en la llamada misma, con una cabecera X-FourA-Limit, es diferente: consulta 403 Not in Your Plan.

Errores de tiempo de espera

Síntoma: Las requests fallan con un error de timeout.

Causa: La página de destino tarda más en cargar que el timeout configurado.

Solución: Aumenta timeout_ms (el valor predeterminado es 15s para single, 30s para browser, 45s para proxy):

curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://slow-site.com",
    "timeout_ms": 60000
  }'

Para requests de navegador, verifica también que tu valor checkText aparezca realmente en la página. Un error tipográfico hace fallar la llamada con checkText:<your text> not found.

403 No incluido en tu plan

Síntoma: La API devuelve 403 con un header X-FourA-Limit y un reason de plan_limit_feature o plan_limit_premium.

{
  "error": "Geo targeting (the exitCountries, exitState, exitCity, exitAsn and exitOs parameters) is not included in your plan (Free). Remove the parameter or upgrade.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}

Causa: Tu plan no incluye el endpoint al que llamaste o el parámetro que enviaste. plan_limit_feature cubre un endpoint excluido, y exitCountries, exitState, exitCity, exitAsn o exitOs sin segmentación geográfica. plan_limit_premium cubre exitClass: premium sin salidas premium, y una solicitud Proxy que especifica una ubicación de salida una vez agotado tu tráfico premium. El destino nunca fue contactado y no se gastó nada.

Solución: Elimina el parámetro, llama a un endpoint incluido en tu plan o actualiza tu plan. La pestaña Límites y funciones de Uso y límites detalla lo que incluye tu plan. No reintentes la solicitud sin cambios: no se incluye Retry-After porque esperar no cambiará la respuesta.

429 Demasiadas solicitudes

Síntoma: La API devuelve 429.

Causa: Una de dos comprobaciones rechazó la llamada, y la respuesta indica cuál fue. Si incluye una cabecera X-FourA-Limit, se alcanzó uno de los límites de tu plan: solicitudes simultáneas o solicitudes por minuto en ese endpoint, solicitudes de Browser para el día, o los créditos o ancho de banda para el período de facturación. Si no incluye dicha cabecera, la asignación compartida por minuto de la plataforma para ese servicio estaba llena, lo que corresponde al tráfico de FourA y no al tuyo.

Solución: Lee X-FourA-Limit primero. Espera cuando el límite esté a unos segundos y detente cuando no sea así. Los límites del plan que se resuelven esperando indican los segundos en la cabecera Retry-After y en retry_after_seconds; el límite compartido los indica en retryAfter:

import time
import requests

# Plan limits that come back in hours or days, not seconds.
STOP_ON = {"plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth"}

def make_request(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code == 429:
            limit = resp.headers.get("X-FourA-Limit")
            if limit in STOP_ON:
                raise Exception(f"stopped by {limit}: {resp.json().get('error')}")
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
            )
            time.sleep(wait)
            continue
        return resp
    raise Exception("Rate limit not resolved after retries")

# Example: single request
make_request(
    "https://eu.api.foura.ai/api/single/",
    {"method": "GET", "url": "https://example.com"}
)

Si el header indicó plan_limit_concurrency o plan_limit_rate, la solución es limitar cuántas llamadas mantienes abiertas y cuántas inicias por minuto, en lugar de reintentar con más agresividad. Reenviar un lote rechazado de inmediato hace que todo el lote sea rechazado nuevamente. Las llamadas rechazadas no cuentan para tu límite por minuto, pero si continúan llegando a más del doble de ese límite, los rechazos se convierten en un periodo de espera: el cuerpo del 429 incluye cooldown: true y te pide pausar durante 30 segundos (retry_after_seconds: 30). Ejecutar requests en paralelo describe el patrón, y Uso y límites en el Dashboard muestra tus contadores en tiempo real junto a tus topes.

503 Servicio no disponible

Síntoma: La API devuelve el estado 503.

Causa: Esto sucede en tres casos:

  1. El servicio está al límite de su capacidad. FourA ya está ejecutando tantos requests en ese motor como se le permite ejecutar a la vez, contabilizados en todo el tráfico y no solo en el tuyo. Service at capacity en el campo error. Por lo general, se restablece en segundos.
  2. Servicio deshabilitado temporalmente. Hay una ventana de mantenimiento en curso. Service disabled en el campo error.
  3. FourA no puede verificar tu clave en este momento. API key check temporarily unavailable en el campo error, con Retry-After: 5. Tu clave es válida.

Los tres casos incluyen un campo retryAfter en la response. Ninguno de ellos es un límite del plan: los límites de tu propio plan siempre responden con un header X-FourA-Limit en un 403 o un 429, nunca con 503.

Solución: Espera retryAfter segundos y luego reintenta:

import time
import requests

def make_request_with_retry(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code in (429, 503):
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
            )
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")

Un 503 por capacidad significa que FourA está ocupado, por lo que aplicar un backoff y reintentar es la solución completa. Si recibes un rechazo con 429 y X-FourA-Limit, el problema es tuyo: reduce la cantidad de requests paralelas en tu pipeline.

504 Tiempo de espera agotado en el servidor ascendente

Síntoma: La API devuelve 504 con {"error": "Upstream timeout"}.

Causa: La tarea no terminó dentro del tiempo límite que declaraste para la request. Un destino lento, la resolución en frío de un challenge o una página muy grande pueden causarlo. No es un problema con tu clave, tus parámetros ni tu proxy.

Solución: Dale más tiempo a la llamada o reintenta. FourA espera el valor de tu timeout_ms más un pequeño margen, por lo que aumentarlo extiende la espera de forma efectiva:

{
  "url": "https://slow-site.com/report",
  "timeout_ms": 90000
}

Para /api/auto/ en un destino protegido, una primera llamada en frío puede tardar decenas de segundos. Su timeout_ms cubre toda la secuencia y acepta hasta 180000.

Cuando el propio /api/auto/ agota ese límite, la llamada sigue respondiendo HTTP 200. El cuerpo incluye un error que comienza con time budget exhausted, y status suele ser 504 (un intento previo fallido puede dejar allí su propio estado). Aumenta timeout_ms o reintenta.

502 Upstream no disponible

Síntoma: La API devuelve 502 con {"error": "Upstream unavailable"}, o 503 con {"error": "Backend service unavailable"}.

Causa: FourA no pudo comunicarse con su propio motor (Upstream unavailable), o el motor no devolvió una respuesta utilizable (Backend service unavailable), normalmente porque una instancia se estaba reiniciando. En /api/browser/, una página espera hasta 10 segundos por un navegador libre cuando todos están ocupados, y una página que siga esperando tras ese tiempo se devuelve como este 503.

Solución: Reintenta con un backoff corto. Ambos se clasifican como service_error, y solo se factura success, por lo que un reintento no te cuesta nada adicional. Si persiste más de uno o dos minutos, consulta la página de estado.

401 Errores de autenticación

Síntoma: Cada request devuelve 401 Unauthorized.

Lista de comprobación:

  1. Verifica que el header sea X-API-Key: YOUR_API_KEY (no Authorization: Bearer ni Api-Key)
  2. Comprueba si hay espacios en blanco adicionales o saltos de línea en tu API key
  3. Genera una clave nueva desde el Dashboard si la actual pudiera estar comprometida

400 Request no válida

Síntoma: Una llamada a POST /api/single/, /api/proxy/ o /api/browser/ devuelve 400 con {"error": "Invalid request: <field>: <reason>; ..."}.

Causa: Falta un campo en el cuerpo de tu request, tiene un tipo incorrecto o está fuera de rango. El mensaje indica cada campo que no pudo aceptar y el motivo, hasta cinco de ellos, seguido de and N more cuando hay más. No se obtuvo nada, el resultado es client_error y no se consumen créditos.

Solución: Corrige los campos indicados y envía la request de nuevo. El mismo cuerpo producirá el mismo 400, así que no la reintentes sin cambios. La referencia del endpoint enumera cada campo con su tipo y límites. En /api/auto/ el mismo error se devuelve como HTTP 200 con status: 400 y el motivo en error.

400 El destino resuelve a una IP privada o reservada

Síntoma: La API devuelve 400 con Refusing to fetch <target>: target resolves to a private or reserved IP range antes de que la request salga de FourA.

Causa: Tu url resuelve a un rango de IP privada, de bucle invertido o reservada (RFC 5735, RFC 6598 o bloques reservados de IPv6). FourA rechaza estos destinos para evitar que su red se use para acceder a hosts internos.

Solución: Haz fetch a una URL pública. Si estás haciendo pruebas, usa un destino público como https://example.com o https://httpbin.org/get. Si el destino previsto es un servicio gestionado por ti, exponlo primero en un hostname público.

{ "error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts." }

Un nombre de host que no se puede resolver no se rechaza. La llamada devuelve HTTP 200 con status: 0 y el motivo (could not resolve <host>: <reason>), como cualquier destino al que FourA no puede acceder, y no se factura.

400 Espacio en la URL

Síntoma: Single, Proxy o Auto devuelve 400 con invalid URL: it contains a space; encode it as %20 (the URL as sent: "...") antes de que la request salga de FourA.

Causa: La URL contiene un espacio o un carácter de control dentro, generalmente un enlace extraído de una página tal como estaba escrito (javascript: void(0), un enlace para compartir con texto dentro). No se obtiene nada, el resultado es client_error y no se gastan créditos.

Solución: Codifica la URL antes de enviarla (un espacio es %20) y omite los enlaces que no sean páginas, como los de tipo javascript:. El modo Browser obtiene dicha URL de la misma forma que lo hace Chrome.

400 El destino es la propia API de FourA

Síntoma: La API devuelve 400 con Refusing to fetch <url>: that is the FourA API itself, not a page. antes de que la request salga de FourA.

Causa: Tu url apunta a api.foura.ai o eu.api.foura.ai. Un crawler suele hacer esto cuando resuelve un enlace relativo de una página tomando como base la URL de la API en lugar de la propia URL de la página, por lo que /category/news/ se convierte en https://eu.api.foura.ai/category/news/. No se obtiene nada y no se gastan créditos.

Solución: Resuelve cada enlace tomando como base la URL de la página de donde proviene antes de enviarlo, por ejemplo con urljoin(page_url, href) en Python. El endpoint Inspect (/inspect) es la única dirección en el host de la API que puedes consultar a través de FourA.

no_eligible_proxy al usar exitCountries

Síntoma: Una llamada a /api/proxy/ con exitCountries devuelve HTTP 200 con un contenedor de error en JSON:

{
  "error": "No eligible proxy found for exit countries: CZ, GB",
  "code": "no_eligible_proxy",
  "details": { "exitCountries": ["CZ", "GB"] },
  "total": 0.084
}

Causa: El pool de proxies actual no tiene ninguna salida activa cuyo país visible para el destino coincida con tu allowlist. El pool estándar nunca recurre a un país no solicitado cuando defines exitCountries. Sin exitCountries, la misma situación responde {"error": "Failed"}: FourA no tenía ninguna salida para probar, así que reintenta después de unos segundos.

Una request que especifica una ubicación de salida (exitState, exitCity, exitAsn, exitOs o exitLifetimeMin, con exitClass: premium) sale únicamente a través de salidas premium. Cuando FourA no tiene más salidas premium para probar, la llamada termina con "error": "No premium exit answered for this request" y el mismo code: no_eligible_proxy.

Solución: Conserva el alcance solicitado y reintenta más tarde. El pool se actualiza aproximadamente cada diez minutos, por lo que un país que no tiene coincidencias ahora a menudo obtiene una en el transcurso de una hora.

import time, requests

def fetch_scoped(url, countries, max_attempts=6, wait_sec=600):
    for _ in range(max_attempts):
        r = requests.post("https://eu.api.foura.ai/api/proxy/",
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json={"maxTries": 5, "exitCountries": countries,
                  "request": {"method": "GET", "url": url}}).json()
        if r.get("code") == "no_eligible_proxy":
            time.sleep(wait_sec)
            continue
        return r
    raise RuntimeError(f"no eligible exit in {countries} after {max_attempts} attempts")

Solo amplía la lista de países si el requisito de país de tu flujo de trabajo cambió genuinamente. Los fallbacks silenciosos a otros países pueden romper la lógica posterior que depende de la ubicación geográfica.

Se rechaza un perfil de navegador

Síntoma: La llamada responde con unknown profile '<id>', no profile matches browser=... o browser profile selection requires unblocker:true.

Causa: El profile, browser, os o version que enviaste no está en el catálogo, o enviaste uno con unblocker: false.

Solución: Consulta GET /api/profiles para ver el catálogo actual, elige uno de él y mantén unblocker activado cuando elijas un navegador.

El cuerpo de la respuesta devuelve texto ilegible

Síntoma: El data (o body) de la respuesta contiene mojibake o caracteres ilegibles cuando el destino utiliza un charset distinto de UTF-8.

Causa: De forma predeterminada, FourA decodifica automáticamente los cuerpos de las respuestas a UTF-8 basándose en el header Content-Type del destino o en una etiqueta HTML <meta charset>. Si el destino miente sobre su charset, obtendrás texto ilegible.

Solución: Para cargas útiles binarias (imágenes, protobuf, audio sin procesar), define returnBuffer: true en la request. Single y Proxy devolverán entonces data como un objeto que contiene los bytes sin procesar, {"type": "Buffer", "data": [<byte values>]}, sin aplicar ninguna transcodificación de charset.

{
  "method": "GET",
  "url": "https://example.com/image.png",
  "returnBuffer": true
}

Para destinos de texto que declaran incorrectamente su charset, decodifica tú mismo los bytes sin procesar: realiza la petición con returnBuffer: true, lee los valores de bytes en data.data y luego decodifícalos con el charset correcto.

HTML inesperado en lugar de JSON

Síntoma: Esperabas JSON del sitio de destino pero recibiste HTML.

Causa: La página de destino puede entregar contenido diferente según los headers.

Solución: Agrega un header Accept y habilita unblocker para obtener headers de navegador realistas:

curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://api.example.com/data",
    "headers": [["Accept", "application/json"]],
    "unblocker": true
  }'

También puedes configurar tryJsonData en true para que FourA parsee automáticamente las respuestas JSON.

El cuerpo es una página de verificación, no el contenido

Síntoma: la llamada tuvo éxito, status es 200, pero data (o body) es una verificación de bots en lugar de la página que querías.

Causa: el objetivo ejecutó una verificación de bots que FourA encontró pero no pudo superar. La respuesta lo indica: Single y Proxy devuelven defense con solved: false, y Browser devuelve defenseSolved: false con el proveedor en defenses.present.

Solución: revisa primero defense.vendor y luego escala. Prueba con un perfil de navegador diferente en Single, pasa a Proxy para obtener una salida distinta o utiliza Browser para que se ejecute JavaScript. Referencia completa de campos y lista de proveedores: Site checks.

Agrega una subcadena en validate.data.accept que solo contenga la página real. Una página de verificación que FourA reconoce nunca se considera un éxito: se devuelve con un header X-FourA-Check-Page y no se factura. Sin validate, una página de verificación que FourA no reconoce, devuelta con HTTP 200, cuenta como un éxito y te enterarás más adelante en lugar de en la llamada.

¿Aún tienes problemas?

Si ninguna de las soluciones anteriores funciona:

  1. Revisa la página de estado para ver si hay incidentes en curso
  2. Revisa las métricas de tus requests en el Dashboard
  3. Contacta a soporte en support@foura.ai con los detalles de tu request (incluye el X-FourA-Request-Id de la respuesta fallida)

Pasos siguientes

Actualizado: 13 de noviembre de 2026