# Rate Limits

> URL: https://foura.ai/pt/docs/api/rate-limits
> Updated: 2026-11-06
> Index: https://foura.ai/llms.txt

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](#requests-per-minute): 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](https://foura.ai/docs/api/endpoints#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](https://foura.ai/docs/dashboard/quota) 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.

```json
{
  "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:

```json
{
  "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](https://foura.ai/docs/api/endpoints#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`:

```json
{
  "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](https://foura.ai/docs/how-to/run-requests-in-parallel) 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.

```json
{
  "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:

```json
{
  "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](https://foura.ai/docs/api/response-headers).

```json
{
  "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.

```json
{
  "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.

```json
{
  "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](https://foura.ai/docs/api/errors)).

## 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](https://foura.ai/dashboard).

### 429: RPM excedido

```json
{
  "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

```json
{
  "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:

```json
{
  "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á:

```python
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](https://foura.ai/docs/dashboard/quota) 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](https://foura.ai/docs/api/proxy-port#responses) para a tabela de status e [How Your Plan Is Metered](https://foura.ai/docs/guides/plans-and-metering) para ver de qual pool os gigabytes da porta são consumidos.

## Relacionados

- [Run Requests in Parallel](https://foura.ai/docs/how-to/run-requests-in-parallel): Um padrão prático de concorrência limitada
- [Usage & Limits](https://foura.ai/docs/dashboard/quota): Todos os limites do plano ao lado do seu uso em tempo real
- [API Endpoints](https://foura.ai/docs/api/endpoints): Referência completa de parâmetros
- [Error Handling](https://foura.ai/docs/api/errors): Todos os tipos de erro e responses
- [Response Headers](https://foura.ai/docs/api/response-headers): `X-FourA-Limit`, `Retry-After` e os demais
- [Troubleshooting](https://foura.ai/docs/troubleshooting/common-issues): Problemas comuns e correções
