Rate limits
Cada request a la API de FourA pasa por tres verificaciones antes de llegar a un motor: los límites de tu propio plan, la cuota compartida de la plataforma para todo el tráfico y la cuota compartida de la plataforma para el endpoint al que llamaste. Cada verificación puede rechazar un request por sí sola, y cada una responde con un body diferente.
Las tres verificaciones, en orden
- Límites del plan. Lo que permite tu propio plan: qué endpoints y parámetros incluye, cuántos requests pueden ejecutarse a la vez por endpoint, cuántos por minuto, cuántos requests de browser por día, y los créditos y el ancho de banda disponibles en el período de facturación.
- Límite global de la plataforma. Todo lo que el host de la API al que llamaste está gestionando en ese momento, independientemente del endpoint al que haya ido el tráfico. Un rechazo aquí reporta
"service": "api". - Límite de la plataforma por endpoint. El tráfico en el servicio single, proxy o browser al que llamaste.
Tu propio plan se evalúa primero, y ese orden es el contrato formal y no un detalle de implementación. Las cuotas compartidas son recursos comunes, por lo que un request que la plataforma siempre iba a rechazar no debe consumirlas de camino al rechazo. Una cuenta que envía mucho más de lo que permite su plan se corta antes de que afecte a los recursos que utilizan los demás.
Las verificaciones 2 y 3 contabilizan el tráfico total de FourA, no el tuyo. Interpreta un rechazo de cualquiera de ellas como "FourA está ocupado", no como "has enviado demasiado". La verificación 1 corresponde únicamente a tu cuenta, y nada más en la plataforma influye en ella.
Un rechazo en cualquiera de las verificaciones compartidas le devuelve a tu cuenta todo lo que su admisión contabilizó, tanto el bucket por minuto como el cupo diario de browser, ya que el request nunca llegó a un backend. Tampoco cuenta para la pausa de reintento descrita en Requests por minuto: fue la capacidad de FourA la que lo rechazó, no tu plan.
POST /api/auto/ no reserva un espacio propio. Las subllamadas de Single, Proxy y Browser que realiza por ti pasan las tres verificaciones como cualquier otro request, por lo que un lote paralelo de llamadas auto se descuenta de tu plan a través de sus subllamadas. (Tus recuentos de requests y la tasa de éxito contabilizan la llamada auto en sí, una sola vez; las subllamadas se muestran como sus intentos).
Límites del plan
Un límite de plan responde con un header X-FourA-Limit que indica qué límite rechazó la llamada. El mismo código aparece en el body bajo reason, de modo que puedes implementar bifurcaciones condicionales sin necesidad de leer los headers. Cada body de límite de plan incluye error, reason y documentation; el resto de los campos depende del límite.
X-FourA-Limit |
Estado | Qué se agotó |
|---|---|---|
plan_limit_feature |
403 | El endpoint al que llamaste, o el parámetro exitCountries, exitState, exitCity, exitAsn o exitOs, no está en tu plan |
plan_limit_premium |
403 | exitClass: premium no está en tu plan, o una request de Proxy especifica una ubicación de salida sin tráfico premium restante |
plan_limit_concurrency |
429 | Requests simultáneas en ese endpoint |
plan_limit_rate |
429 | Requests por minuto en ese endpoint |
plan_limit_browser_daily |
429 | Requests de navegador para el día |
plan_limit_credits |
429 | Créditos facturados para el periodo de facturación |
plan_limit_bandwidth |
429 | Ancho de banda para el periodo de facturación |
Los números detrás de cada límite corresponden a tu plan, y la pestaña Límites y funciones de Uso y límites los muestra junto a tu uso en tiempo real. No los definas fijos en el código: cada rechazo incluye el tope que lo rechazó.
Una request rechazada no consume nada. El resultado es rate_limit, y solo se factura success.
Endpoint o parámetro no incluido en el plan
Un 403 con plan_limit_feature significa que la llamada solicitó algo que el plan no incluye. La verificación se ejecuta antes de contabilizar nada, por lo que la llamada rechazada no afecta tus contadores de rate limit ni diarios.
{
"error": "The browser endpoint is not included in your plan (Free). Upgrade to use it.",
"reason": "plan_limit_feature",
"documentation": "https://foura.ai/prices"
}
El mismo código y estado responden a una llamada de POST /api/proxy/ que establece exitCountries, exitState, exitCity, exitAsn o exitOs en un plan sin geo targeting. La cadena error nombra el parámetro:
{
"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"
}
plan_limit_premium tiene el mismo formato para exitClass: premium en un plan sin salidas premium. Un plan que incluye salidas premium pero ha consumido el tráfico premium de este periodo no es rechazado, a menos que una request de Proxy indique una ubicación de salida: la request se atiende desde el pool estándar y la response reporta exitClass: standard. Ninguno de los dos casos consume una salida premium. Consulta exitClass.
Ningún 403 define Retry-After. Esperar no cambia el resultado.
Requests simultáneas
La concurrencia se contabiliza por endpoint: tu plan incluye un límite para Single, uno para Proxy y uno para Browser. La request que exceda el límite devolverá un 429 con Retry-After: 1:
{
"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
}
in_flight también cuenta la request rechazada, por lo que muestra al menos una más que limit.
La solución es limitar tu propio paralelismo en lugar de reintentar con más insistencia. Responder a un 429 reenviando el mismo lote de inmediato genera otro 429 para cada llamada en él. Consulta Ejecutar requests en paralelo para ver un patrón práctico.
Requests por minuto
Single y Proxy incluyen una cuota por minuto, medida en una ventana deslizante de un minuto. Solo las requests admitidas cuentan para ella: una request rechazada se descuenta, por lo que una cuenta que solicita de forma constante un poco más de su cuota recibe su cuota en lugar de que se le rechace casi todo.
{
"error": "Rate limit reached: your plan allows 600 single requests per minute. Cool down and retry.",
"reason": "plan_limit_rate",
"documentation": "https://foura.ai/prices",
"limit_per_minute": 600,
"current_rate": 613,
"retry_after_seconds": 17
}
retry_after_seconds indica cuánto tiempo falta para que se admita una request más, si no envías nada más mientras tanto: al menos 1 segundo y como máximo 120. El header Retry-After incluye el mismo valor.
Reintentar requests rechazadas más rápido que eso tiene su propia regla. Cuando las requests rechazadas por este límite en el minuto móvil superan el doble del límite, la llamada se rechaza con una pausa de 30 segundos:
{
"error": "Rate limit cooldown: 1250 requests over your plan's 600 single requests per minute were refused in the last minute and kept arriving. Pause for 30 seconds.",
"reason": "plan_limit_rate",
"documentation": "https://foura.ai/prices",
"limit_per_minute": 600,
"current_rate": 540,
"refused_last_minute": 1250,
"cooldown": true,
"retry_after_seconds": 30
}
Los rechazos durante la pausa no se contabilizan, por lo que la pausa finaliza por sí sola a medida que avanza el minuto, incluso para un cliente que sigue reintentando. Para distinguir la pausa del límite habitual, lee cooldown en lugar del texto error.
Browser requests por día
Browser no tiene un límite por minuto. El límite de su plan es una cantidad de browser requests por día, contabilizadas desde la medianoche UTC, y el contador registra cada browser request admitida, no solo las exitosas. Una llamada de Browser que falla del lado de FourA con cero créditos, como el 503 Backend service unavailable, devuelve su cupo diario. Las respuestas de Browser y Auto que tus límites no rechazaron incluyen el recuento y el límite en los headers X-FourA-Browser-Used-Today y X-FourA-Browser-Limit-Per-Day: consulta Response Headers.
{
"error": "Daily browser limit reached: your plan allows 300 browser requests per day (resets at midnight UTC).",
"reason": "plan_limit_browser_daily",
"documentation": "https://foura.ai/prices",
"limit_per_day": 300,
"used_today": 301
}
Este rechazo no incluye ningún retry_after_seconds ni encabezado Retry-After, ya que la espera es de horas en lugar de segundos. Trátalo como una detención y programa la siguiente ejecución para la medianoche UTC.
Créditos para el periodo de facturación
Solo cuentan los créditos facturados, lo que significa únicamente las requests exitosas. Cuando el total facturado alcanza los créditos disponibles para ti en este periodo, se rechazan las requests adicionales hasta que se reinicie el periodo o compres más.
{
"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"
}
hard_stop es la cantidad de créditos facturados en la que las requests se detienen durante este período. Léelo directamente del body en lugar de calcularlo: ya incluye cualquier crédito que hayas comprado además del plan.
Ancho de banda para el período de facturación
Los planes que incluyen un límite de ancho de banda rechazan requests una vez que el tráfico estándar de este período lo alcanza. El tráfico premium tiene su propia asignación y no cuenta para este límite. El ancho de banda comprado cuenta igual que el ancho de banda incluido, y la cadena error indica lo que tienes disponible, no solo lo que incluye el plan.
{
"error": "Bandwidth limit reached: 50 GB is available to you this billing period.",
"reason": "plan_limit_bandwidth",
"documentation": "https://foura.ai/prices",
"used_bytes": 53687091200,
"limit_bytes": 53687091200,
"retry_after_seconds": 86400,
"resets_at": "2026-10-01T00:00:00.000Z"
}
En ambos límites de período, retry_after_seconds tiene un límite máximo de 24 horas; resets_at es el instante exacto en que se reinicia el período.
Campos de límites del plan
| Campo | Tipo | Presente en | Descripción |
|---|---|---|---|
error |
string | todos | Mensaje legible por humanos, incluido el número al que estás sujeto |
reason |
string | todos | plan_limit_ más el nombre del límite. Mismo valor que el encabezado X-FourA-Limit. |
documentation |
string | todos | Enlace a la página de planes |
retry_after_seconds |
number | concurrency, rate, credits, bandwidth | Cuánto tiempo esperar. Mismo valor que el encabezado Retry-After. |
limit |
number | concurrency | Requests simultáneas que el plan permite en ese endpoint |
in_flight |
number | concurrency | Requests en ejecución en ese endpoint para tu cuenta, incluida la rechazada |
limit_per_minute |
number | rate | Requests por minuto que el plan permite en ese endpoint |
current_rate |
number | rate | Requests contabilizadas en el minuto deslizante, incluida la rechazada |
refused_last_minute |
number | rate pause | Requests que la cuota por minuto rechazó en el minuto deslizante. Solo en la pausa de 30 segundos. |
cooldown |
boolean | rate pause | true en la pausa de 30 segundos por reintentar demasiado rápido. Ausente en un rechazo común por minuto. |
limit_per_day |
number | browser daily | Requests de browser que el plan permite por día |
used_today |
number | browser daily | Requests de browser contabilizadas hoy, incluida la rechazada |
used |
number | credits | Créditos facturados hasta el momento en este período |
hard_stop |
number | credits | Créditos facturados en los que las requests se detienen en este período |
used_bytes |
number | bandwidth | Tráfico estándar hasta el momento en este período, en bytes. El tráfico premium no está incluido. |
limit_bytes |
number | bandwidth | Bytes disponibles en este período |
resets_at |
string | credits, bandwidth | Timestamp ISO 8601 del final del período |
Los límites del plan usan retry_after_seconds. Los límites de la plataforma a continuación usan retryAfter. Un helper de reintento necesita leer ambos, o leer el encabezado Retry-After, que establecen los límites del plan y también el 503 API key check temporarily unavailable (consulta Errores).
Límites de la plataforma
Las verificaciones de la plataforma rastrean dos aspectos por servicio y uno más en todos ellos:
- Concurrencia: cuántas requests está ejecutando FourA al mismo tiempo.
- RPM: cuántas requests ha recibido FourA en los últimos 60 segundos.
Ambos contadores son compartidos por todos los que usan ese servicio. current y limits en las respuestas a continuación describen la plataforma, no tu cuenta. Si deseas ver tu propio número, lee in_flight desde una respuesta de límite del plan o abre Usage & Limits en el dashboard.
429: RPM Exceeded
{
"error": "Rate limit exceeded",
"status": 429,
"service": "single",
"retryAfter": 5,
"current": {
"concurrency": 12,
"rpm": 3000
},
"limits": {
"maxConcurrency": 500,
"maxRpm": 3000
}
}
El servicio alcanzó el límite de requests permitidos para el último minuto. Espera retryAfter segundos.
503: Concurrencia excedida
{
"error": "Service at capacity",
"status": 503,
"service": "proxy",
"retryAfter": 2,
"current": {
"concurrency": 500,
"rpm": 1200
},
"limits": {
"maxConcurrency": 500,
"maxRpm": 3000
}
}
El servicio está ejecutando tantas requests como tiene permitido de forma simultánea. Esto se libera en segundos.
Servicio deshabilitado
Cuando un servicio se desconecta temporalmente por mantenimiento, la API devuelve 503 con un mensaje de error diferente:
{
"error": "Service disabled",
"status": 503,
"service": "single",
"retryAfter": 60,
"current": { "concurrency": 0, "rpm": 0 },
"limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
Esto no es un rate limit. El servicio no está disponible temporalmente. Revisa el valor de retryAfter y vuelve a intentarlo tras esa cantidad de segundos. Por lo general, esto se resuelve en cuestión de minutos.
Ambas variantes de 503 contienen las mismas claves, así que bifurca según la cadena error y nunca en función de qué campos están presentes. Service disabled corresponde a mantenimiento, Service at capacity a concurrencia.
En la variante de mantenimiento, current.concurrency y current.rpm siempre son 0: la request se rechazó antes de medir nada.
Campos de límites de la plataforma
| Campo | Tipo | Descripción |
|---|---|---|
error |
string | Mensaje de error legible para humanos |
status |
number | Código de estado HTTP (429 o 503) |
service |
string | Qué servicio rechazó la llamada: single, proxy, browser o api |
retryAfter |
number | Tiempo de espera recomendado en segundos antes de reintentar |
current.concurrency |
number | Requests que el servicio ejecutaba en todos los clientes al rechazar |
current.rpm |
number | Requests que el servicio procesó en todos los clientes en los últimos 60 segundos |
limits.maxConcurrency |
number | Límite compartido de concurrencia del servicio |
limits.maxRpm |
number | Límite compartido por minuto del servicio |
Cómo gestionar cada rechazo con un único helper
Retry-After se define en los límites de plan por los que vale la pena esperar, retry_after_seconds está en sus bodies y retryAfter está en los bodies de la plataforma. Lee los tres en ese orden y detén el proceso ante límites de plan que ninguna espera solucionará:
import time
import requests
# Plan limits that a short wait never clears.
STOP_ON = {
"plan_limit_feature",
"plan_limit_premium",
"plan_limit_browser_daily",
"plan_limit_credits",
"plan_limit_bandwidth",
}
def wait_seconds(resp, attempt):
header = resp.headers.get("Retry-After")
if header and header.isdigit():
return int(header)
try:
body = resp.json()
except ValueError:
return 2 ** attempt
return body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt
def fetch(url, api_key, max_retries=5):
for attempt in range(max_retries):
resp = requests.post(
"https://eu.api.foura.ai/api/single/",
headers={"X-API-Key": api_key, "Content-Type": "application/json"},
json={"method": "GET", "url": url},
)
limit = resp.headers.get("X-FourA-Limit")
if limit in STOP_ON:
raise RuntimeError(f"stopped by plan limit {limit}: {resp.json().get('error')}")
if resp.status_code in (429, 503):
time.sleep(wait_seconds(resp, attempt))
continue
return resp
raise RuntimeError("Max retries exceeded")
Una cuota diaria no se restablece hasta pasadas varias horas, y una cuota por periodo tarda días en recuperarse, así que trátalas como una detención en lugar de una espera. Lee resets_at del cuerpo si deseas programar la próxima ejecución.
Consejos
- Limita el número de requests que mantienes en curso en lugar de reintentar un lote rechazado. Una tormenta de reintentos convierte un solo 429 en muchos.
- Lee primero
X-FourA-Limit. Te indica en una sola cadena si el límite corresponde a tu cuenta o a la plataforma, y ningún rechazo de la plataforma lo define. - No fijes los números en el código. Cada respuesta de límite de plan incluye el tope que la rechazó, y Uso y límites los muestra todos.
retryAfteren límites de plataforma es fijo según el tipo: 2 segundos para concurrencia, 5 para RPM, 60 para mantenimiento.- Compara contra
errorpara diferenciar los dos errores 503. Ambas estructuras contienencurrentylimits, por lo que comprobar si "esos campos existen" interpretará el mantenimiento como un problema de concurrencia. - Un error 403 con
X-FourA-Limitestá relacionado con tu plan, no con el sitio de destino. El destino nunca respondió.
El puerto de proxy tiene sus propios valores
Todo lo anterior se refiere a la API JSON. El tráfico que envías a través de proxy.foura.ai está sujeto a un conjunto independiente de valores del plan, en una unidad distinta: túneles abiertos a la vez, aperturas de túneles por minuto y el tráfico estándar para el periodo de facturación. Esos rechazos llegan como un código de estado HTTP con un header X-Foura-Error en lugar de un cuerpo JSON, ya que un CONNECT no tiene cuerpo para incluirlo. Consulta Puerto de proxy para ver la tabla de estados y Cómo se mide tu plan para saber de qué fondo se descuentan los gigabytes del puerto.
Relacionado
- Ejecución de requests en paralelo: Un patrón práctico de concurrencia acotada
- Uso y límites: Cada límite del plan junto a tu uso en tiempo real
- Endpoints de la API: Referencia completa de parámetros
- Manejo de errores: Todos los tipos de error y respuestas
- Headers de respuesta:
X-FourA-Limit,Retry-Aftery el resto - Solución de problemas: Problemas comunes y soluciones