# Errores de la API

> URL: https://foura.ai/es/docs/api/errors
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

Cómo manejar errores de la API de FourA.

## Formato de respuesta de error

La API devuelve objetos JSON planos para todos los errores. No hay un objeto `error` anidado. Cuando un fallo tiene un código legible por máquina, este aparece como un campo de nivel superior: `reason` en un límite de plan, `code` en una llamada de proxy sin una salida válida.

```json
{
  "error": "Invalid API key"
}
```

Algunos errores incluyen campos adicionales como `status`, `service`, `retryAfter`, `current` o `limits` en el nivel superior:

```json
{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": { "concurrency": 12, "rpm": 3000 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
```

## Rastrear una request

Cada response de la API (éxito o error) incluye un header `X-FourA-Request-Id` con un UUID para esa llamada, excepto si FourA no puede leer el body en absoluto (JSON malformado o un body superior a 100 KB): eso se rechaza antes de asignar un ID. Regístralo en tus logs. Si necesitas preguntar a soporte qué ocurrió con una request específica, ese ID nos permite encontrarla.

```bash
curl -i -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://example.com"}'
# HTTP/1.1 200 OK
# X-FourA-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
# Content-Type: application/json
# ...
```

## Tipos de error

### 400: Bad Request

El cuerpo de la solicitud no contiene campos obligatorios, incluye valores no válidos o especifica un destino que la API se niega a consultar.

Un cuerpo que no sea un objeto o array JSON se considera JSON mal formado y recibe `Invalid JSON in request body`, como se muestra a continuación.

En Single, Proxy Finder y Browser, un campo que falta, tiene un tipo incorrecto o está fuera de rango se indica en el mensaje como `<field>: <reason>`. Los campos anidados se unen con puntos (`validate.status.accept`). Se enumeran hasta cinco problemas, separados por `; `, y cualquier problema adicional finaliza el mensaje como `and <n> more`:

```json
{
  "error": "Invalid request: url: Invalid input: expected string, received undefined"
}
```

Es un `client_error` y no se factura. Auto reporta un campo que no puede aceptar dentro de un HTTP 200 en su lugar, como se describe más abajo en Lectura de fallos de `/api/auto/`.

El mismo 400 también cubre la protección SSRF. Si tu `url` se resuelve en un rango de IP privado, de bucle invertido o reservado de otro modo (RFC 5735, RFC 6598, bloques reservados de IPv6), la request se rechaza antes de salir de la red de FourA:

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

`<target>` es la dirección, o el nombre de host y la dirección a la que se resolvió. Una URL que no se puede analizar, o que no es `http://` o `https://`, recibe el mismo 400.

Un destino en el propio host de la API de FourA (`eu.api.foura.ai` o `api.foura.ai`) también recibe un 400, en Single, Proxy Finder, Browser y Auto, antes de realizar cualquier petición o cobro. Por lo general, significa que un enlace extraído de una página se resolvió contra la URL de la API en lugar de la de la propia página:

```json
{
  "error": "Refusing to fetch <url>: that is the FourA API itself, not a page. A link taken from a page was probably resolved against the API URL; resolve it against the page's own URL."
}
```

`<url>` es el destino exactamente como lo enviaste. La página de [Inspect](https://foura.ai/docs/api/inspect) es la única excepción: FourA aún obtiene `https://eu.api.foura.ai/inspect` por ti.

Una URL con un espacio o un carácter de control dentro también recibe un 400, en Single, Proxy Finder y Auto, antes de que se obtenga o cobre nada. Un enlace copiado de una página tal como está escrito a menudo contiene uno (`javascript: void(0)`, un enlace para compartir con espacios en su texto). Codifícalo, un espacio como `%20`. Browser obtiene dicha URL de la misma forma que lo hace Chrome:

```json
{
  "error": "invalid URL: it contains a space; encode it as %20 (the URL as sent: \"https://example.com/a b\")"
}
```

Un nombre de host que no se puede resolver no se rechaza. La llamada responde como HTTP 200 con `status: 0` y el motivo (`could not resolve <host>: <reason>`), y no se factura. Un destino al que FourA intenta conectarse pero del que no obtiene respuesta HTTP (límite de redirecciones, tiempo de espera de conexión o lectura, o un reinicio) también responde como HTTP 200, con `error` y `total_time` y sin `status`: consulta [Resultados de la solicitud](https://foura.ai/docs/api/outcomes#what-a-failed-call-looks-like).

En Single, un cuerpo de respuesta que supere los 128 MB tras la descodificación se detiene ahí. La llamada responde como HTTP 200 con `"error": "Response body exceeds the 128 MB limit"` y no se factura.

Un JSON con formato incorrecto en el cuerpo se rechaza de la misma manera, antes de leer cualquier campo:

```json
{
  "error": "Invalid JSON in request body"
}
```

Los campos `proxy` y `ignoreProxies` tienen sus propios errores 400. Ambos aceptan los proxy IDs opacos devueltos por respuestas anteriores, por lo que cualquier otra cosa no se podrá decodificar:

| Mensaje | Qué ocurrió |
|---------|---------------|
| `Invalid proxy format` | El valor de `proxy` no es un proxy ID emitido por FourA. Una dirección de proxy sin procesar termina aquí. |
| `Invalid ignoreProxies format` | Una de las entradas en `ignoreProxies` no es un proxy ID. |
| `Proxy not found` | El ID se decodificó correctamente pero ya no resuelve a una salida activa. Elige una nueva. |
| `Managed exit: this proxy id cannot be pinned to a request` | La salida existe, pero no es una que FourA mantenga abierta para una petición específica. El ID de una salida premium termina aquí cuando tu plan no tiene más tráfico premium disponible. Reutiliza la sesión en la que se devolvió, o ejecuta la llamada a través de `POST /api/proxy/` y utiliza la salida que elija. |

**Solución:** Comprueba que tu petición incluya todos los campos obligatorios, que las URLs usen `http://` o `https://` con cualquier espacio codificado como `%20`, que el host resuelva a una dirección pública y que cualquier valor de `proxy` sea un ID copiado textualmente de una respuesta anterior.

Estos son resultados de `client_error`: la petición nunca salió de FourA, por lo que no se consumió nada en tu nombre.

### 401: Unauthorized

Tu API key falta o no es válida.

Falta la key:

```json
{
  "error": "Missing API key. Include X-API-Key header."
}
```

Clave no válida:

```json
{
  "error": "Invalid API key"
}
```

**Solución:** verifica que tu header `X-API-Key` contenga una key válida. Genera una nueva key desde el [Dashboard](https://foura.ai/dashboard) si es necesario.

Un 401 siempre significa que FourA verificó tu key y la rechazó. Cuando FourA no puede verificar una key durante unos segundos, responde 503 `API key check temporarily unavailable` (ver más abajo), nunca 401.

### 403: No incluido en tu plan

La llamada solicitó un endpoint o un parámetro que tu plan no incluye. La response establece `X-FourA-Limit` e incluye el mismo código en el body bajo `reason`:

```json
{
  "error": "The browser endpoint is not included in your plan (Free). Upgrade to use it.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}
```

`reason` es `plan_limit_feature` para un endpoint que el plan excluye o para `exitCountries` y los campos de ubicación de salida en un plan sin geo targeting, y `plan_limit_premium` para `exitClass: premium` en un plan sin salidas premium, o para una [ubicación de salida](https://foura.ai/docs/api/endpoints#exit-location) sin tráfico premium restante. La cadena `error` nombra el endpoint o parámetro.

Un 403 de FourA nunca se debe al sitio de destino: el destino nunca fue contactado. Un 403 que devolvió el destino llega como HTTP 200 con `status: 403` dentro del body.

**Solución:** Elimina el parámetro, llama a un endpoint que tu plan incluya o actualiza tu plan. No se establece ningún `Retry-After`, porque esperar no cambia la respuesta. No se gastó nada: el resultado es `rate_limit`, y solo se factura `success`.

### 413: Carga útil demasiado grande

El body JSON de la request es más grande de lo que FourA acepta (100 KB). La respuesta no es JSON y no incluye `X-FourA-Request-Id`, porque el body se rechaza antes de leerse.

**Solución:** Envía un payload `data` más pequeño. No se gastó nada.

### 429: Límite de tasa alcanzado

Dos verificaciones distintas responden con 429 y no incluyen los mismos campos.

**Los propios límites de tu plan.** La response incluye un header `X-FourA-Limit` que indica qué límite rechazó la llamada y coloca el mismo código en el body bajo `reason`:

```json
{
  "error": "Concurrency limit reached: your plan allows 50 simultaneous proxy request(s). Retry when an in-flight request finishes.",
  "reason": "plan_limit_concurrency",
  "documentation": "https://foura.ai/prices",
  "limit": 50,
  "in_flight": 51,
  "retry_after_seconds": 1
}
```

`reason` es uno de `plan_limit_concurrency`, `plan_limit_rate`, `plan_limit_browser_daily`, `plan_limit_credits` o `plan_limit_bandwidth`. Cuando esperar ayuda, el tiempo de espera se encuentra en `retry_after_seconds` y en el header `Retry-After`, nunca en `retryAfter`. `plan_limit_browser_daily` no incluye ninguno de los dos, ya que el límite se restablece a medianoche UTC y no en segundos. No se gastó nada: el resultado es `rate_limit`, y solo se factura `success`.

**El límite compartido de la plataforma.** Sin header `X-FourA-Limit`, y el tiempo de espera está en `retryAfter`:

```json
{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": { "concurrency": 12, "rpm": 3000 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
```

`current` y `limits` describen el servicio en todo el tráfico, no en tu cuenta. Un rechazo aquí significa que FourA está ocupado.

**Solución:** Espera según lo que indique `Retry-After`, `retry_after_seconds` o `retryAfter` en la respuesta. Ante un límite de concurrencia o rate limit, limita cuántas requests mantienes abiertas en lugar de reenviar el lote rechazado. Ante un límite diario o del período de facturación, detén la ejecución. Consulta [Límites de tasa](https://foura.ai/docs/api/rate-limits) para ver cada campo y [Ejecutar requests en paralelo](https://foura.ai/docs/how-to/run-requests-in-parallel) para conocer el patrón.

### 500: Error del servidor

Algo salió mal de nuestro lado.

**Solución:** Reintenta la request después de una breve pausa. Si el error persiste, consulta la [página de estado](https://updates.foura.ai/status) o contacta a soporte con el `X-FourA-Request-Id` de la respuesta fallida.

### 502: Upstream no disponible

FourA no pudo obtener una respuesta de su propio motor (`Upstream unavailable`: la conexión falló) o recibió una que no pudo leer (`Malformed JSON from backend`).

```json
{
  "error": "Upstream unavailable",
  "details": "..."
}
```

**Solución:** Reintenta con un breve backoff. Esto es de nuestro lado, por lo que no te cuesta nada: el resultado es `service_error` y solo se factura `success`.

### 504: Tiempo de espera agotado en el servidor ascendente

El motor no terminó dentro del tiempo asignado para esta request.

```json
{
  "error": "Upstream timeout",
  "details": "the backend did not finish inside the time budget for this request"
}
```

Un error 504 se debe al tiempo que tomó el trabajo, no a tu clave, tus parámetros ni tu proxy. Los destinos lentos, las resoluciones de desafíos en frío y las páginas grandes son las causas habituales.

**Solución:** Aumenta `timeout_ms` en la request (Single acepta hasta 120000, Browser hasta 120000, Auto hasta 180000) o reintenta. FourA espera el presupuesto que declaraste más un pequeño margen, por lo que solicitar más tiempo realmente te da más tiempo.

### 503: Servicio deshabilitado o a máxima capacidad

Un error 503 significa que el servicio no está disponible temporalmente por mantenimiento o que el límite de concurrencia de la plataforma está lleno. Ambas variantes incluyen las mismas claves: `error`, `status`, `service`, `retryAfter`, `current` y `limits`. Distínguelas por la cadena `error`, no por los campos presentes.

```json
{
  "error": "Service disabled",
  "status": 503,
  "service": "single",
  "retryAfter": 60,
  "current": { "concurrency": 0, "rpm": 0 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
```

`Service disabled` indica mantenimiento y `current` muestra `0` para ambos contadores, ya que la request fue rechazada antes de medir nada. `Service at capacity` es el formato de concurrencia, y allí `current` contiene el uso real de la plataforma. Consulta [Rate Limits](https://foura.ai/docs/api/rate-limits) para ver esa estructura.

**Solución:** Espera `retryAfter` segundos y luego reintenta. La página de estado enumera las ventanas de mantenimiento activas.

Una tercera variante de 503 no tiene `retryAfter`. Significa que el motor detrás de tu endpoint no pudo aceptar tu llamada: se estaba reiniciando, falló del lado de FourA antes de que se ejecutara tu request o (en Browser) todos los navegadores permanecieron ocupados durante los 10 segundos que una página espera por uno. `backend_status` es el estado propio del motor y `detail` es el inicio de su respuesta:

```json
{
  "error": "Backend service unavailable",
  "backend_status": 503,
  "detail": "..."
}
```

Es un `service_error` y no se factura. Reintenta después de uno o dos segundos. Una request que es incorrecta en sí misma nunca llega aquí: recibe un 400 que indica el campo.

Un cuarto 503 significa que FourA no pudo confirmar tu API key por un momento, por ejemplo, mientras su base de datos realiza una conmutación. Tu clave no es el problema y no se ejecutó nada. Incluye `Retry-After: 5` y la misma espera en `retryAfter`:

```json
{
  "error": "API key check temporarily unavailable",
  "status": 503,
  "retryAfter": 5
}
```

No se factura. Reintenta después de `retryAfter` segundos. Una key que FourA haya confirmado en los últimos 10 minutos sigue funcionando durante este tipo de situaciones, por lo que esta respuesta es poco común.

## Cómo leer fallos desde `/api/auto/`

`POST /api/auto/` responde con HTTP 200 siempre que el ladder se haya ejecutado, incluso cuando fallaron todos los niveles. El resultado real se encuentra en el body:

```json
{
  "status": 403,
  "error": "exit blocked by the target defense",
  "attempts": 7,
  "meta": { "rung": "fail", "solved": false, "attempts": 7, "credits": 47 }
}
```

`status` es el último estado con el que respondió el objetivo, o 502 cuando ningún intento logró alcanzarlo (504 cuando el presupuesto de tiempo se agotó primero). Cada respuesta fallida de una secuencia que se ejecutó también incluye un `attemptReport` que contabiliza con qué se toparon los intentos, con un `summary` de una sola línea seguro para registrar en logs, y `meta.attemptsByEngine` y `meta.browserRequests` indican lo que envió la llamada. Consulta [Por qué falló una llamada Auto](https://foura.ai/docs/guides/smart-fetch#why-an-auto-call-failed). Un campo de la request que Auto no pueda aceptar (por ejemplo, un `timeout_ms` inferior a 5000 o superior a 180000) se devuelve de la misma forma: HTTP 200 con `"status": 400` y el motivo en `error`, antes de realizar cualquier intento y sin coste alguno.

Por lo tanto, no uses bifurcaciones basadas en el estado de transporte para Auto. En su lugar, lee `status` y `error` del body. Un estado distinto de 200 genuino procedente de `/api/auto/` significa que FourA rechazó la llamada antes de iniciar la secuencia, o que no pudo completarla: 400 (JSON mal formado, un objetivo privado o reservado, o un objetivo en el propio host de la API de FourA), 401, 413, 502, 503 o 504. Hay un límite del plan que se responde directamente en la entrada: `exitClass: premium` en un plan sin salidas premium recibe un 403 con `X-FourA-Limit: plan_limit_premium`, antes de que se realice ningún trabajo. Cualquier otro límite, ya sea tuyo o de la plataforma, se devuelve dentro del 200 con su estado en el body.

Cuando un sitio ha fallado varias llamadas Auto consecutivas realizadas con tu API key, Auto responderá de inmediato a las siguientes llamadas de esa clave hacia dicho sitio durante un tiempo, sin intentarlo: `"error": "target temporarily unservable, retry later"`, `"status": 503` y un `retryAfter` en segundos. No tiene coste; espera `retryAfter` segundos.

Un límite del plan alcanzado por una de las subllamadas también se devuelve como HTTP 200. El body es el rechazo en sí, con su `reason`, además de `status` y `meta`, y la response incluye el mismo header `X-FourA-Limit` que un rechazo directo:

```json
{
  "status": 429,
  "error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 75000,
  "hard_stop": 75000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z",
  "meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}
```

Qué límites detienen la escalera y cuáles solo cierran un peldaño se detalla en [Smart Fetch (Auto)](https://foura.ai/docs/guides/smart-fetch#when-your-plans-limits-meet-the-ladder).

## Fallos del lado del destino dentro de 200 OK

No todos los fallos se manifiestan como un estado HTTP no 2xx. Cuando el destino responde HTTP 200 pero la respuesta de FourA incluye un `error` (por ejemplo, tus reglas `validate` rechazaron el body) o el body es una página de verificación que FourA reconoce, el resultado es `application_error`. Cuando el destino devuelve un estado distinto de 200 que tus reglas `validate` no aceptan, el resultado es `application_fail` y el body se entrega sin cambios.

Ninguno de los dos casos se factura: solo se factura `success`. Una llamada de Browser que encuentra todos los navegadores ocupados espera hasta 10 segundos a que uno se libere. Si ninguno lo hace, regresa como el 503 `Backend service unavailable` descrito arriba. Browser también puede responder HTTP 200 con `"error": "No available browser slot"` cuando no pudo obtener un navegador en absoluto. Ninguno se factura. Reintenta después de unos segundos, o mantén menos llamadas de Browser abiertas al mismo tiempo. La referencia de [Resultados](https://foura.ai/docs/api/outcomes) cubre la taxonomía completa.

Una llamada Single mediante un `proxy` fijado por ti también puede responder HTTP 200 con `"error": "The exit gave the same answer for <n> different sites"` junto al body. FourA detectó que esa salida entregó la misma página a sitios no relacionados, por lo que la página pertenece a la salida y no es la que solicitaste. Es `application_error` y no se factura. Obtén una salida nueva desde `POST /api/proxy/`, que descarta este tipo de salida por sí solo.

Lo mismo aplica cuando la propia red de la salida responde en lugar del sitio. La llamada regresa con `"error": "The exit answered instead of the site (<name>)"` o `"error": "Corporate web gateway intercepted the request (<name>)"` (una página de inicio de sesión o de filtrado, o una redirección a una de ellas), con `"error": "The exit intercepted TLS and answered instead of the site (<name>)"` cuando la salida respondió en lugar del sitio mismo, o con `"error": "Honeypot echo proxy (plaintext request dump)"` cuando la salida devolvió una copia de tu propia solicitud. FourA comprueba esto sin importar lo que indiquen tus reglas `validate`, descargas `returnBuffer` incluidas. Ninguno de ellos se factura. Obtén una salida nueva de la misma manera.

## Codificación de respuestas

FourA decodifica automáticamente los cuerpos de las respuestas a UTF-8. Si el destino sirve `windows-1251`, `gbk`, `shift_jis`, `iso-8859-*` o cualquier otro juego de caracteres declarado en la cabecera `Content-Type` o en una etiqueta HTML `<meta charset>`, recibes una cadena UTF-8 limpia en el campo `data` (single, proxy) o `body` (browser).

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

## Estrategia de reintentos

Una política práctica de reintentos:

```python
import time
import requests

# Plan limits that no short wait will clear: stop the run instead of retrying.
STOP_ON = {
    "plan_limit_feature",
    "plan_limit_premium",
    "plan_limit_browser_daily",
    "plan_limit_credits",
    "plan_limit_bandwidth",
}

def make_request(url, payload, api_key, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.post(
            url,
            headers={"X-API-Key": api_key, "Content-Type": "application/json"},
            json=payload,
        )
        if resp.status_code == 200:
            return resp.json()

        body = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {}
        request_id = resp.headers.get("X-FourA-Request-Id", "?")

        limit = resp.headers.get("X-FourA-Limit")
        if limit in STOP_ON:
            raise RuntimeError(f"{limit} (request {request_id}): {body.get('error')}")

        # Plan limits send Retry-After and retry_after_seconds; platform limits send retryAfter.
        header = resp.headers.get("Retry-After")
        retry_after = (
            int(header) if header and header.isdigit()
            else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt
        )

        if resp.status_code in (429, 503):
            time.sleep(retry_after)
            continue
        if resp.status_code >= 500:   # 500, 502, 503, 504 are all ours to fix
            time.sleep(2 ** attempt)
            continue

        # 400/401/403/404 won't fix themselves
        raise RuntimeError(f"{resp.status_code} (request {request_id}): {body.get('error')}")

    raise RuntimeError(f"Exhausted {max_retries} retries")
```

## Los fallos de proxy incluyen un reporte

Una llamada de `POST /api/proxy/` que agota los intentos se devuelve como HTTP 200 con un contenedor de error, no como un código de error HTTP. La cadena de error es corta y siempre tiene el mismo formato, por lo que un objeto `attemptReport` la acompaña con los conteos:

```json
{
  "error": "Download maxTry limit reached",
  "attemptReport": {
    "total": 25,
    "noResponse": 0,
    "defense": 0,
    "contentRejected": 25,
    "statusRejected": 0,
    "other": 0,
    "vendors": [],
    "profilesTried": ["default"],
    "summary": "25 attempt(s): 25 returned HTTP 200 with no defense present and were rejected only by your validate.data - the page was fetched, your content rule did not match it"
  },
  "total": 34.812
}
```

Registra `attemptReport.summary` junto al error y sabrás si las salidas estaban bloqueadas, caídas o entregando páginas que tus propias reglas de `validate` rechazaron. Referencia de campos y qué hacer con cada recuento: [Por qué una request de proxy se quedó sin intentos](https://foura.ai/docs/troubleshooting/proxy-attempt-report).

## Relacionado

- [Límites de tasa](https://foura.ai/docs/api/rate-limits): Límites del plan, concurrencia y detalles de RPM
- [Ejecutar requests en paralelo](https://foura.ai/docs/how-to/run-requests-in-parallel): Cómo mantenerte por debajo de la concurrencia de tu plan
- [Resultados de requests](https://foura.ai/docs/api/outcomes): Explicación de los siete valores de resultado
- [Problemas comunes](https://foura.ai/docs/troubleshooting/common-issues): Síntomas, causas y soluciones
- [Comprobaciones del sitio](https://foura.ai/docs/api/site-checks): Cuando el body es una página de desafío en lugar de un error
- [Por qué una request de proxy se quedó sin intentos](https://foura.ai/docs/troubleshooting/proxy-attempt-report): Cómo leer `attemptReport`
