Resultados de la request

Cada request a la API de FourA se clasifica en exactamente un outcome, y lo mismo ocurre con cada túnel a través del puerto proxy. El outcome se calcula una sola vez, al final de la llamada, y se registra contra la credencial que la realizó. Tu panel de control, el feed de actividad y la 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 outcome: consulta Implicaciones de facturación.

Los siete outcomes

Estos son los siete estados en los que puede terminar un request. Un túnel utiliza cinco de ellos: consulta más abajo Los túneles usan el mismo vocabulario.

Outcome Capa Qué significa
success n/a Se entregó una response válida. Cuenta para tu cuota facturable.
application_error target El destino devolvió HTTP 200, pero el body contenía un campo de error, o el body es una verificación de bots o una página de rechazo que FourA reconoce.
application_fail target El destino devolvió un estado distinto de 200 que tus reglas validate no aceptaron o para el cual no enviaste validate, o bien no hubo ninguna response, incluyendo un nombre de host de destino que no se puede resolver.
client_error caller Tu request fue rechazada antes de salir de FourA. Parámetros incorrectos, valor de proxy mal formado, URL protegida por SSRF.
rate_limit FourA La request fue rechazada 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 agotar el límite asignado), o por la cuota compartida de RPM o concurrencia de la plataforma.
service_error FourA El motor respondió con un error de servidor, o su body no era JSON válido.
service_fail FourA La red propia de FourA falló: su motor no respondió a tiempo, la conexión se interrumpió o te desconectaste.

La columna de capa te indica quién es el responsable:

  • Los outcomes de tipo 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 outcomes de tipo caller significan que tu request nunca tuvo oportunidad de ejecutarse. Corrige la estructura de la request.
  • Los outcomes de tipo FourA son responsabilidad nuestra. Reintenta la operación y consulta la página de estado si persisten.

Si un sitio de destino devuelve 403, el resultado es application_fail, no client_error. Tu llamada estaba bien formada. El sitio simplemente dijo que no.

Cómo se ve una llamada fallida

Una llamada que llegó a FourA y se ejecutó regresa como HTTP 200, sin importar lo que haya sucedido después. Solo un rechazo previo a la obtención (400, 401, 403, 413, 429) o una falla del lado de FourA (5xx) utiliza otro estado HTTP. Por lo tanto, el outcome se lee desde el body, no desde el estado del transporte.

Body Qué sucedió Resultado
status: 200, headers, data, sin error La página fue entregada. success
status distinto de 200, headers, data, sin error El destino respondió y no enviaste validate. Su respuesta está en data. application_fail
status distinto de 200, headers, data y error El destino respondió y tus reglas de validate lo rechazaron, por ejemplo Status 404 is not in accept list 200. application_fail
status: 200, headers, data y error El destino respondió HTTP 200 y tus reglas de validate lo rechazaron, por ejemplo Data not in accept list ["product"]. application_error
error y total_time únicamente, sin status, sin data El destino nunca respondió con HTTP: se alcanzó el límite de redirecciones (Number of redirects hit maximum amount), la conexión o la lectura expiraron, la conexión se reinició o la respuesta estaba vacía. El texto es el motivo propio del motor. application_fail
status: 0 y error, nada más No se puede resolver el nombre de host: could not resolve <host>: <reason>. Ningún motor se ejecutó, y en Auto no hay meta. Reintentar no cambiará nada hasta que cambie el DNS. application_fail

Un bucle de redirección, tal como lo ve la quinta fila:

{
  "error": "Number of redirects hit maximum amount",
  "total_time": 0.808
}

En POST /api/proxy/, una llamada que agota sus intentos incluye error: Download maxTry limit reached y un attemptReport con los conteos (consulta API Errors). En POST /api/auto/, un ladder que se ejecutó y falló incluye status, error, attempts, un attemptReport con las causas, y meta.rung establecido en fail.

X-FourA-Credits informa el trabajo realizado, incluso ante un fallo. La facturación solo cuenta success, por lo que ninguna de las estructuras fallidas anteriores se cobra.

El éxito reconoce validate

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

Con validate, el éxito sigue las reglas que declaraste. Si le indicas a la API que tanto 200 como 403 son aceptables para una request determinada, un 403 se devuelve como success. El body te sigue llegando 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, o una página de rechazo que un sitio sirve con HTTP 200. Esa request es application_error y no se factura. El cuerpo aún te llega sin cambios, y el header X-FourA-Check-Page nombra la página.

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 en el lado de FourA, en el lado del destino o en tu propio lado son todos gratuitos.

La tabla se refiere a los créditos. El tráfico premium se contabiliza aparte: 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 él. 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 también termina en uno de estos resultados, por lo que un solo conjunto de etiquetas cubre ambos productos. Solo cinco de los siete pueden ocurrir, porque los dos resultados target requieren 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 recibió.
client_error FourA no abrirá ese túnel: una dirección privada o reservada, o un puerto que no ofrece.
rate_limit Se alcanzó uno de los límites de tu plan (túneles abiertos a la vez, aperturas de túnel por minuto, el tráfico estándar del periodo, tráfico premium que no tienes), o el puerto mismo estaba al límite de su capacidad 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 mediante ninguna salida que FourA intentó: DNS, timeout, 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 te lo muestra en tus propios términos en lugar de los nuestros. Una opción que FourA no puede procesar se responde con 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 del 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 máxima o su tasa de apertura. Vuelve a intentarlo en un momento.
port not served FourA no abre túneles hacia ese puerto
private address No se puede acceder a direcciones privadas y reservadas

Nada relacionado con un túnel se factura en créditos, ya que un túnel no tiene una request a la que cobrarlos. En su lugar, el puerto mide los bytes. Consulta Cómo se mide el consumo de tu plan.

Lectura de resultados en el panel de control

Cada request que realiza tu API key aparece en el feed de Activity con su etiqueta de resultado. Las páginas de Metrics y Overview agregan este mismo campo para los gráficos circulares y las líneas de tiempo.

Cuando filtras Activity por resultado, también puedes enfocarte en un único endpoint (Auto, Single, Proxy Finder, Browser) para comprobar si un tipo de fallo es específico 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 inicial basada en los resultados:

Resultado ¿Es seguro reintentar? Cuándo
success n/a Ya tienes la response.
application_error A veces Lee el body del error del destino. Algunos son transitorios, la mayoría no. Si X-FourA-Check-Page está establecido, 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, no como la respuesta final.
application_fail A veces Si el destino te está aplicando rate limit, reduce la frecuencia. Si te está bloqueando, cambia al endpoint Proxy o Browser.
client_error No La request volverá a fallar del mismo modo. Corrige los datos de entrada.
rate_limit Depende Respeta el tiempo de espera indicado en la response: Retry-After, retry_after_seconds o retryAfter. En plan_limit_browser_daily, detén las requests hasta la medianoche UTC; en plan_limit_credits o plan_limit_bandwidth, detén las requests 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 en service_error.
Actualizado: 11 de noviembre de 2026