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

  1. 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.
  2. 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".
  3. 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-Limit primeiro. 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.
  • retryAfter nos limites da plataforma é fixo por tipo: 2 segundos para concorrência, 5 para RPM, 60 para manutenção.
  • Compare por error para diferenciar os dois 503s. Ambos os formatos contêm current e limits, portanto uma verificação de "esses campos existem?" interpreta manutenção como um problema de concorrência.
  • Um 403 com X-FourA-Limit diz 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.

Atualizado em: 6 de novembro de 2026