Docs › Referencia API › Resultados de request

Resultados de request

Cada request a la API de FourA se clasifica exactamente en un resultado, al igual que cada túnel a través del puerto proxy. El resultado se calcula una vez, al final de la llamada, y se registra en la credencial que la realizó. Tu panel de control, feed de actividad y facturación leen el mismo campo.

Solo success consume créditos. El tráfico premium se contabiliza aparte de los créditos y no depende del resultado: consulta Billing Implications.

The Seven Outcomes

Estos son los siete resultados en los que puede terminar un request. Un túnel utiliza cinco de ellos: consulta Tunnels Use the Same Vocabulary más abajo.

Outcome Layer What it means
success n/a Se entregó una response válida. Se descuenta de tu cuota facturable.
application_error target El destino devolvió HTTP 200, pero el body incluía un campo de error, o el body es una página de verificación de bots que FourA reconoce.
application_fail target El destino devolvió un código que no es 2xx y que tus reglas validate no aceptaron, o ninguna response en absoluto, incluido un nombre de host de destino que no se puede resolver.
client_error caller Tu request fue rechazado antes de salir de FourA. Parámetros incorrectos, valor de proxy malformado, URL bloqueada por protección SSRF.
rate_limit FourA El request fue rechazado antes de ejecutarse: por uno de los límites de tu plan (un 403 para un endpoint o parámetro que el plan no incluye, un 429 por un límite agotado), o por el límite compartido de RPM o concurrencia de la plataforma.
service_error FourA El motor respondió con un error del servidor, o su body no era un JSON válido.
service_fail FourA La propia red de FourA falló: su motor no respondió a tiempo, la conexión se interrumpió o te desconectaste.

La columna Layer indica quién es el responsable:

  • Los resultados de target corresponden al sitio al que llamaste. Tu request llegó bien a FourA, y FourA llegó bien al destino. El propio destino devolvió un error.
  • Los resultados de caller significan que tu request nunca tuvo oportunidad de ejecutarse. Corrige la estructura del request.
  • Los resultados de FourA son responsabilidad nuestra. Reintenta y revisa la status page si persisten.

Que un sitio de destino devuelva 403 es application_fail, no client_error. Tu llamada estaba bien formada. El sitio simplemente la rechazó.

Success Is validate-Aware

Sin validate, la API marca un request como success solo cuando el destino devuelve HTTP 200.

Con validate, el éxito sigue las reglas que hayas declarado. Si le indicas a la API que tanto 200 como 403 son aceptables para un request determinado, un 403 se devuelve como success. El body sigue llegándote sin cambios.

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://target.example/feed",
    "validate": {
      "status": { "accept": [200, 403] }
    }
  }'

En esta llamada, una respuesta 403 cuenta como success y se factura como una request. Una respuesta 500 cuenta como application_fail y no se factura.

La misma lógica se aplica a validate.headers y validate.data. Cualquier respuesta que el motor acepte según tus reglas se devuelve como success independientemente del estado HTTP.

Una respuesta nunca es success, con o sin validate: un HTTP 200 cuyo cuerpo es una página de verificación de bots que FourA reconoce, como una tarea de verificación visual o una página que solo pide al navegador ejecutar JavaScript. Esa request es application_error y no se factura. El cuerpo te sigue llegando sin cambios, y el header X-FourA-Check-Page nombra la página de verificación.

Implicaciones de facturación

Resultado Facturable Cuenta para la cuota
success Sí Sí
application_error No No
application_fail No No
client_error No No
rate_limit No No
service_error No No
service_fail No No

Solo se facturan las requests que entregaron los datos que solicitaste. Los fallos del lado de FourA, del lado del destino o de tu propio lado son todos gratuitos.

La tabla se refiere a los créditos. El tráfico premium se contabiliza aparte de ellos: una request que intentó una salida premium cuenta el tráfico que transportó ese intento, cualquiera que sea el resultado, porque la salida se utilizó de todos modos. Un intento que aún se estaba ejecutando cuando otra salida respondió se detiene de inmediato, y el tráfico que transportó hasta entonces también cuenta.

El tráfico estándar tampoco depende del resultado: en un plan con límite de ancho de banda, el tráfico de cada request cuenta para dicho límite. Una request rechazada por uno de los límites de tu propio plan no contabiliza tráfico.

Los túneles usan el mismo vocabulario

Un túnel a través del puerto proxy termina también en uno de estos resultados, por lo que un único conjunto de etiquetas cubre ambos productos. Solo pueden ocurrir cinco de los siete, porque los dos resultados target necesitan que FourA haya visto la respuesta del destino, y la respuesta de un túnel es tu propio tráfico cifrado.

Resultado En un túnel, esto significa
success El túnel se abrió y tu herramienta lo obtuvo.
client_error FourA no abrirá ese túnel: una dirección privada o reservada, o un puerto al que no da servicio.
rate_limit Se alcanzó uno de los límites de tu plan (túneles abiertos simultáneamente, aperturas de túnel por minuto, el tráfico estándar del periodo, tráfico premium que no tienes), o el puerto en sí estaba en su capacidad máxima o tasa de apertura.
service_error FourA no tenía salida para lo que solicitaste. Suele ser temporal.
service_fail No se pudo alcanzar el destino a través de ninguna salida que FourA intentó: DNS, tiempo de espera agotado, conexión rechazada.
application_error Nunca ocurre en un túnel.
application_fail Nunca ocurre en un túnel.

Un rechazo también incluye un motivo breve, y el panel de control lo muestra en tus propios términos en lugar de los nuestros. Una opción que FourA no puede procesar se responde 400 en la propia conexión y no registra ninguna fila, por lo que nunca aparece aquí.

Motivo en pantalla Qué se agotó
port not in plan Tu plan no incluye el puerto proxy
tunnels at once Todos los túneles simultáneos permitidos por tu plan estaban en uso
openings per minute Se agotaron las aperturas de túneles por minuto de tu plan
traffic used up Se agotó el tráfico de tu plan para este período
premium not available El tráfico premium no está disponible en tu plan en este momento
port was full El puerto en sí alcanzó su capacidad o tasa de apertura máxima. Inténtalo de nuevo en un momento.
port not served FourA no abre túneles hacia ese puerto
private address No se puede acceder a direcciones privadas o reservadas

Ningún aspecto de un túnel se factura en créditos, ya que un túnel no tiene una request a la cual cobrarlos. En su lugar, el puerto mide bytes. Consulta Cómo se mide tu plan.

Lectura de resultados en el panel de control

Cada request que realiza tu API key aparece en el feed de Actividad con su etiqueta de resultado. Las páginas de Métricas y Información general agregan el mismo campo para gráficos de dona y líneas de tiempo.

Cuando filtras la Actividad por resultado, también puedes enfocarte en un único endpoint (Auto, Single, Proxy Finder, Browser) para ver si una clase de fallo es específica de alguno de ellos. Cambia el Producto de la página a Proxy y las mismas etiquetas de resultado filtrarán tus túneles.

Heurísticas de reintento

Una política de reintento de primera pasada basada en los resultados:

Resultado ¿Reintento seguro? Cuándo
success N/A Ya tienes la response.
application_error A veces Lee el cuerpo de error del destino. Algunos son transitorios, la mayoría no. Si X-FourA-Check-Page está definido, el sitio mostró una página de verificación: envía la URL a Auto, que trata una página de verificación como un paso a superar y no como la respuesta definitiva.
application_fail A veces Si el destino te está aplicando rate limit, reduce la velocidad. Si te está bloqueando, cambia al endpoint Proxy o Browser.
client_error No La request volverá a fallar de la misma manera. Corrige los datos de entrada.
rate_limit Depende Respeta la espera que te indica la response: Retry-After, retry_after_seconds o retryAfter. En caso de plan_limit_browser_daily, detén los envíos hasta la medianoche UTC; en plan_limit_credits o plan_limit_bandwidth, detente hasta resets_at; en plan_limit_feature o plan_limit_premium, modifica la request.
service_error Sí Backoff exponencial corto.
service_fail Sí Igual que service_error.

Temas relacionados

Actualizado: 27 de septiembre de 2026
← Endpoint Inspect Encabezados de respuesta →