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. |
Contenido relacionado
- Errores de la API: Respuestas de error a nivel HTTP
- Puerto del proxy: Códigos de estado con los que llega el rechazo de un túnel
- Límites de tasa: Qué activa
rate_limity las dos formas en que se devuelve - Métricas: Dónde ver los resultados desglosados
- Registro de actividad: Historial de resultados por request