# Problemas comunes

> URL: https://foura.ai/es/docs/troubleshooting/common-issues
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

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:

```bash
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:

```bash
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](#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):

```bash
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`.

```json
{
  "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](https://foura.ai/docs/api/endpoints#exit-location) 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](https://foura.ai/docs/dashboard/quota) 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`:

```python
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](https://foura.ai/docs/how-to/run-requests-in-parallel) describe el patrón, y **Uso y límites** en el [Dashboard](https://foura.ai/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:

```python
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:

```json
{
  "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](https://updates.foura.ai/status).

## 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](https://foura.ai/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](https://foura.ai/docs/api/endpoints) 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.

```json
{ "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](https://foura.ai/docs/api/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:

```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.

```python
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`](https://foura.ai/docs/api/endpoints#browser-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.

```json
{
  "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:

```bash
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](https://foura.ai/docs/api/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](https://updates.foura.ai/status) para ver si hay incidentes en curso
2. Revisa las métricas de tus requests en el [Dashboard](https://foura.ai/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

- [Error Handling](https://foura.ai/docs/api/errors): referencia de códigos de error de la API
- [Rate Limits](https://foura.ai/docs/api/rate-limits): todos los límites de plan y límites de la plataforma, con sus campos
- [Request Outcomes](https://foura.ai/docs/api/outcomes): cómo los resultados clasifican lo que sucedió
- [Site checks](https://foura.ai/docs/api/site-checks): qué te indica el campo `defense`
- [Choosing the Right Endpoint](https://foura.ai/docs/guides/choosing-task-type): elige el mejor enfoque para tu objetivo
- [Dashboard Overview](https://foura.ai/docs/dashboard/overview): monitorea tus requests
