Docs › Resolución › Problemas comunes

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 le falta el contenido esperado.

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

Solución: Cambie del endpoint single al endpoint browser. Use checkText para verificar que el contenido se 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 browser devuelve el contenido en el campo body (no en data).

Páginas 403 Forbidden o CAPTCHA

Síntoma: La API devuelve HTML que contiene un desafío CAPTCHA o una página de acceso denegado.

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

Solución: Use el endpoint 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, aumente maxTries para dar más intentos a la rotación de proxy.

Errores de timeout

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

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

Solución: Aumente 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 las requests de browser, verifique también que el valor de checkText realmente aparezca en la página. Un error tipográfico siempre causará un timeout.

429 Too Many Requests (Límite de RPM)

Síntoma: La API devuelve un estado 429 con un mensaje de "rate limit exceeded".

Causa: Ha excedido su límite de requests por minuto (RPM). Esto es diferente de los límites de concurrencia (ver 503 a continuación).

Solución: Use el campo retryAfter de la response para esperar la cantidad de tiempo adecuada antes de volver a intentarlo:

import time
import requests

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:
            body = resp.json()
            wait = body.get("retryAfter", 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"}
)

Consulte su uso actual en el Dashboard para ver sus rate limits.

503 Service Unavailable

Síntoma: La API devuelve un estado 503.

Causa: Esto sucede en dos casos:

  1. Límite de concurrencia alcanzado. Tiene demasiadas requests simultáneas en ejecución. Esto es diferente de 429, que limita las requests por minuto. Con 503, no ha excedido sus RPM, pero ha alcanzado el número máximo de requests que pueden ejecutarse al mismo tiempo.
  2. Servicio temporalmente deshabilitado. Hay una ventana de mantenimiento en curso.

Ambos casos incluyen un campo retryAfter en la response.

Solución: Espere los segundos indicados en retryAfter y luego vuelva a intentarlo:

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):
            body = resp.json()
            wait = body.get("retryAfter", 2 ** i)
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")

Si alcanza los límites de concurrencia 503 con regularidad, reduzca el número de requests paralelas en su pipeline de scraping, o verifique el límite de concurrencia de su plan en el Dashboard.

Errores de autenticación 401

Síntoma: Cada request devuelve 401 Unauthorized.

Checklist:

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

HTML inesperado en lugar de JSON

Síntoma: Esperaba JSON del sitio de destino pero recibió HTML.

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

Solución: Agregue un header Accept y habilite 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 puede establecer tryJsonData en true para que FourA parsee automáticamente las responses JSON.

¿Aún tiene problemas?

Si ninguna de las soluciones anteriores funciona:

  1. Consulte la página de estado para ver si hay incidentes en curso
  2. Revise las métricas de sus requests en el Dashboard
  3. Póngase en contacto con el soporte en support@foura.ai con los detalles de su request

Siguientes pasos

Actualizado: 27 de abril de 2026