Rate Limits
Toda requisição da API FourA passa por três verificações antes de alcançar um engine: os limites do seu próprio plano, depois a cota compartilhada da plataforma para todo o tráfego e, por fim, a cota compartilhada da plataforma para o endpoint chamado. Cada verificação pode recusar uma requisição por conta própria, e cada uma responde com um corpo diferente.
As Três Verificações, em Ordem
- Limites do plano. O que seu próprio plano permite: quais endpoints e parâmetros ele inclui, quantas requisições podem ser executadas simultaneamente por endpoint, quantas por minuto, quantas requisições de browser por dia, além dos créditos e da largura de banda disponíveis no período de faturamento.
- Limite global da plataforma. Tudo o que o host da API chamado está processando naquele momento, independentemente do endpoint para o qual o tráfego foi direcionado. Uma recusa aqui reporta
"service": "api". - Limite da plataforma por endpoint. Tráfego no serviço single, proxy ou browser que você chamou.
O seu próprio plano é avaliado primeiro, e essa ordem é um contrato, não um detalhe de implementação. As cotas compartilhadas são recursos comuns; portanto, uma requisição que a plataforma recusaria de qualquer forma não deve consumi-las a caminho da recusa. Uma conta que envia muito mais do que seu plano permite é interrompida antes de tocar em qualquer recurso compartilhado com outros usuários.
As verificações 2 e 3 contabilizam o tráfego total da FourA, não o seu. Interprete uma recusa de qualquer uma delas como "a FourA está ocupada", e não como "você enviou requisições demais". A verificação 1 diz respeito unicamente à sua conta, e nada mais na plataforma interfere nela.
Uma recusa de qualquer verificação compartilhada devolve à sua conta tudo o que a admissão contabilizou, tanto a cota por minuto quanto a cota diária de browser, já que a requisição nunca alcançou um backend. Ela também não conta para a pausa de repetição descrita em Requisições por minuto: a capacidade da FourA recusou a requisição, não o seu plano.
POST /api/auto/ não ocupa uma cota própria. As subchamadas Single, Proxy e Browser que ele faz para você passam pelas três verificações como qualquer outra requisição; portanto, um lote paralelo de chamadas auto consome o seu plano por meio dessas subchamadas. (As contagens de requisição e a taxa de sucesso contabilizam a chamada auto em si, uma única vez; as subchamadas são exibidas como tentativas dela.)
Limites do Plano
Um limite do plano responde com um header X-FourA-Limit identificando qual limite recusou a chamada. O mesmo código está no corpo sob reason, para que você possa criar condicionais sem precisar ler headers. Todo corpo de limite de plano contém error, reason e documentation; os demais campos dependem do limite.
X-FourA-Limit |
Status | O que esgotou |
|---|---|---|
plan_limit_feature |
403 | O endpoint chamado, ou o parâmetro exitCountries, exitState, exitCity, exitAsn ou exitOs, não está no seu plano |
plan_limit_premium |
403 | exitClass: premium não está no seu plano, ou uma request de Proxy especifica uma exit location sem tráfego premium restante |
plan_limit_concurrency |
429 | Requests simultâneas nesse endpoint |
plan_limit_rate |
429 | Requests por minuto nesse endpoint |
plan_limit_browser_daily |
429 | Requests de navegador no dia |
plan_limit_credits |
429 | Créditos faturados no período de faturamento |
plan_limit_bandwidth |
429 | Largura de banda no período de faturamento |
Os números de cada limite dependem do seu plano, e a aba Limits & Features de Usage & Limits lista esses valores ao lado do seu uso em tempo real. Não defina esses valores no código: cada recusa informa o limite máximo aplicado.
Uma request recusada não consome créditos. O resultado é rate_limit, e apenas success é cobrado.
Endpoint ou parâmetro fora do plano
Um 403 com plan_limit_feature significa que a chamada solicitou algo que o plano não inclui. A verificação ocorre antes de qualquer contagem, portanto a chamada recusada não afeta seu rate limit nem seus contadores diários.
{
"error": "The browser endpoint is not included in your plan (Free). Upgrade to use it.",
"reason": "plan_limit_feature",
"documentation": "https://foura.ai/prices"
}
O mesmo código e status respondem a uma chamada POST /api/proxy/ que define exitCountries, exitState, exitCity, exitAsn ou exitOs em um plano sem geo targeting. A string error especifica o 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 tem o mesmo formato para exitClass: premium em um plano sem saídas premium. Um plano que inclui saídas premium, mas gastou o tráfego premium deste período, não é recusado, a menos que uma request de Proxy especifique um local de saída: a request é atendida a partir do pool padrão e a response reporta exitClass: standard. Nenhum dos casos consome uma saída premium. Consulte exitClass.
Nenhum dos erros 403 define Retry-After. Esperar não altera a resposta.
Requests simultâneas
A concorrência é contabilizada por endpoint: seu plano possui um limite para Single, um para Proxy e um para Browser. A request que ultrapassa o limite retorna como 429 com 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 também conta a request recusada, portanto ele lê pelo menos um a mais do que limit.
A solução é limitar seu próprio paralelismo em vez de tentar novamente com mais intensidade. Responder a um 429 reenviando o mesmo lote imediatamente gera outro 429 para cada chamada nele. Consulte Executar Requests em Paralelo para ver um padrão prático.
Requests por minuto
Single e Proxy têm um limite por minuto, medido em uma janela deslizante de um minuto. Apenas as requests aceitas contam para esse limite: uma request recusada é removida da contagem, de modo que uma conta que faz requisições de forma constante ligeiramente acima do seu limite recebe o volume permitido em vez de ter quase tudo recusado.
{
"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 quanto tempo falta para que mais uma request seja aceita, se você não enviar mais nada nesse intervalo: no mínimo 1 segundo e no máximo 120. O header Retry-After contém o mesmo valor.
Tentar novamente requests recusadas mais rápido do que isso tem uma regra própria. Quando as requests recusadas por esse limite dentro do minuto móvel ultrapassam o dobro do limite permitido, a chamada é recusada com uma 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
}
Recusas durante a pausa não são contabilizadas, portanto a pausa termina por conta própria com o avançar do minuto, mesmo para um cliente que continua tentando novamente. Para diferenciar a pausa do limite normal, leia cooldown em vez do texto error.
Browser requests por dia
O Browser não tem limite por minuto. O limite do seu plano é uma quantidade de browser requests por dia, contados a partir da meia-noite UTC, e o medidor contabiliza cada browser request admitido, não apenas os bem-sucedidos. Uma chamada de Browser que falha do lado do FourA com zero créditos, como o 503 Backend service unavailable, devolve o seu slot diário. Respostas do Browser e do Auto que não foram recusadas pelos seus limites trazem a contagem e o limite nos headers X-FourA-Browser-Used-Today e X-FourA-Browser-Limit-Per-Day: consulte 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
}
Esta recusa não contém retry_after_seconds nem o header Retry-After, pois o tempo de espera é de horas em vez de segundos. Trate isso como uma parada e agende a próxima execução para a meia-noite UTC.
Créditos para o período de faturamento
Apenas créditos faturados contam, o que significa apenas requests bem-sucedidas. Quando o total faturado atinge os créditos disponíveis para você neste período, novas requests são recusadas até que o período seja reiniciado ou você compre mais.
{
"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 é o total de créditos faturados no qual as requests são interrompidas neste período. Leia esse valor diretamente do body em vez de calculá-lo: ele já inclui quaisquer créditos adicionais adquiridos além do plano.
Largura de banda para o período de faturamento
Planos com limite de largura de banda recusam requests assim que o tráfego padrão deste período atinge o teto. O tráfego premium tem sua própria franquia e não conta para este limite. A largura de banda adquirida conta da mesma forma que a largura de banda inclusa, e a string error informa o que está disponível para você, não apenas o que o plano inclui isoladamente.
{
"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"
}
Em ambos os limites de período, retry_after_seconds é limitado a 24 horas; resets_at é o instante exato em que o período é renovado.
Campos de limite do plano
| Campo | Tipo | Presente em | Descrição |
|---|---|---|---|
error |
string | todos | Mensagem legível por humanos, incluindo o limite aplicado a você |
reason |
string | todos | plan_limit_ mais o nome do limite. Mesmo valor que o header X-FourA-Limit. |
documentation |
string | todos | Link para a página de planos |
retry_after_seconds |
number | concurrency, rate, credits, bandwidth | Quanto tempo esperar. Mesmo valor que o header Retry-After. |
limit |
number | concurrency | Requests simultâneos que o plano permite nesse endpoint |
in_flight |
number | concurrency | Requests em execução nesse endpoint para a sua conta, incluindo o que foi recusado |
limit_per_minute |
number | rate | Requests por minuto que o plano permite nesse endpoint |
current_rate |
number | rate | Requests contabilizados no minuto móvel, incluindo o que foi recusado |
refused_last_minute |
number | rate pause | Requests recusados pelo limite por minuto no minuto móvel. Presente apenas na pausa de 30 segundos. |
cooldown |
boolean | rate pause | true na pausa de 30 segundos por tentar novamente rápido demais. Ausente em uma recusa comum por minuto. |
limit_per_day |
number | browser daily | Requests de browser que o plano permite por dia |
used_today |
number | browser daily | Requests de browser contabilizados hoje, incluindo o que foi recusado |
used |
number | credits | Créditos faturados até agora neste período |
hard_stop |
number | credits | Créditos faturados em que os requests são interrompidos neste período |
used_bytes |
number | bandwidth | Tráfego padrão até agora neste período, em bytes. Tráfego premium não está incluído. |
limit_bytes |
number | bandwidth | Bytes disponíveis neste período |
resets_at |
string | credits, bandwidth | Timestamp ISO 8601 do fim do período |
Limites de plano usam retry_after_seconds. Os limites de plataforma abaixo usam retryAfter. Um helper de retry precisa ler ambos, ou ler o header Retry-After, definido por limites de plano e também pelo 503 API key check temporarily unavailable (consulte Erros).
Limites da plataforma
As verificações da plataforma monitoram duas métricas por serviço e mais uma em todos eles:
- Concurrency: quantos requests o FourA está executando ao mesmo tempo.
- RPM: quantos requests o FourA recebeu nos últimos 60 segundos.
Ambos os contadores são compartilhados por todos que usam esse serviço. current e limits nas respostas abaixo descrevem a plataforma, não a sua conta. Se você quiser seu próprio número, leia in_flight de uma resposta de limite de plano ou abra Usage & Limits no dashboard.
429: RPM excedido
{
"error": "Rate limit exceeded",
"status": 429,
"service": "single",
"retryAfter": 5,
"current": {
"concurrency": 12,
"rpm": 3000
},
"limits": {
"maxConcurrency": 500,
"maxRpm": 3000
}
}
O serviço atingiu as requests permitidas no último minuto. Aguarde retryAfter segundos.
503: Concorrência Excedida
{
"error": "Service at capacity",
"status": 503,
"service": "proxy",
"retryAfter": 2,
"current": {
"concurrency": 500,
"rpm": 1200
},
"limits": {
"maxConcurrency": 500,
"maxRpm": 3000
}
}
O serviço está executando tantas requests quanto permitido simultaneamente. Isso se normaliza em segundos.
Serviço Desativado
Quando um serviço fica temporariamente offline para manutenção, a API retorna 503 com uma mensagem de erro diferente:
{
"error": "Service disabled",
"status": 503,
"service": "single",
"retryAfter": 60,
"current": { "concurrency": 0, "rpm": 0 },
"limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
Isto não é um rate limit. O serviço está temporariamente indisponível. Verifique o valor de retryAfter e tente novamente após esse número de segundos. Isso normalmente se resolve em minutos.
Ambos os formatos de 503 contêm as mesmas chaves, portanto, faça a ramificação com base na string error e nunca em quais campos estão presentes. Service disabled é manutenção, Service at capacity é simultaneidade.
No formato de manutenção, current.concurrency e current.rpm são sempre 0: a request foi recusada antes que qualquer medição fosse feita.
Campos de Limite da Plataforma
| Campo | Tipo | Descrição |
|---|---|---|
error |
string | Mensagem de erro legível por humanos |
status |
number | Código de status HTTP (429 ou 503) |
service |
string | Qual serviço recusou a chamada: single, proxy, browser ou api |
retryAfter |
number | Tempo de espera recomendado em segundos antes de tentar novamente |
current.concurrency |
number | Requests que o serviço estava executando em todos os clientes quando recusou |
current.rpm |
number | Requests recebidas pelo serviço em todos os clientes nos últimos 60 segundos |
limits.maxConcurrency |
number | Limite compartilhado de simultaneidade do serviço |
limits.maxRpm |
number | Limite compartilhado por minuto do serviço |
Tratando Cada Recusa com um Único Helper
Retry-After é definido nos limites do plano pelos quais vale a pena esperar, retry_after_seconds está nos corpos deles e retryAfter está nos corpos da plataforma. Leia todos os três nessa ordem e pare nos limites do plano que nenhuma espera resolverá:
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")
Uma franquia diária não retorna por horas, e uma franquia de período não retorna por dias, portanto trate-as como uma parada em vez de uma espera. Leia resets_at do body se você quiser agendar a próxima execução.
Dicas
- Limite o número de requests em andamento em vez de tentar novamente um lote recusado. Uma tempestade de retentativas transforma um 429 em muitos.
- Leia
X-FourA-Limitprimeiro. Ele informa em uma única string se o limite é seu ou da plataforma, e nenhuma recusa da plataforma o define. - Não defina os números diretamente no código. Cada response de limite do plano inclui o teto que o recusou, e Usage & Limits mostra todos eles.
retryAfternos limites da plataforma é fixo por tipo: 2 segundos para concorrência, 5 para RPM, 60 para manutenção.- Compare por
errorpara diferenciar os dois 503s. Ambos os formatos contêmcurrentelimits, portanto uma verificação de "esses campos existem?" interpreta manutenção como um problema de concorrência. - Um 403 com
X-FourA-Limitdiz respeito ao seu plano, não ao site de destino. O destino nunca respondeu.
A Porta do Proxy Tem Seus Próprios Números
Tudo acima diz respeito à API JSON. O tráfego enviado por proxy.foura.ai segue um conjunto separado de limites do plano, em uma unidade diferente: túneis abertos simultaneamente, aberturas de túnel por minuto e o tráfego padrão do período de faturamento. Essas recusas chegam como um status HTTP com um header X-Foura-Error em vez de um body JSON, pois um CONNECT não possui body para incluir um. Consulte Proxy Port para a tabela de status e How Your Plan Is Metered para ver de qual pool os gigabytes da porta são consumidos.
Relacionados
- Run Requests in Parallel: Um padrão prático de concorrência limitada
- Usage & Limits: Todos os limites do plano ao lado do seu uso em tempo real
- API Endpoints: Referência completa de parâmetros
- Error Handling: Todos os tipos de erro e responses
- Response Headers:
X-FourA-Limit,Retry-Aftere os demais - Troubleshooting: Problemas comuns e correções