Rate Limits

Cada request da API FourA passa por rate limiting. Você encontrará dois tipos de limites: concorrência (requests simultâneos) e RPM (requests por minuto). Ambos são aplicados por serviço.

Como Funcionam os Rate Limits

A API aplica limites em dois níveis:

1. Limite global da API: aplica-se a todos os requests, independentemente do endpoint. Esta verificação ocorre primeiro.
2. Limite por serviço: aplica-se separadamente a cada endpoint (single, proxy, browser). Esta verificação só ocorre se o limite global for aprovado.

Se o limite global for atingido, a verificação por serviço não é executada. Um request deve passar por ambas as verificações antes de chegar ao backend.

Cada nível monitora duas métricas:

• Concorrência: quantos requests estão em execução simultaneamente.
• RPM: quantos requests você enviou nos últimos 60 segundos.

Responses de Rate Limit

Quando você atinge um limite, a API retorna uma response JSON com seu uso atual e os limites em vigor.

429: RPM Excedido

{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": {
    "concurrency": 12,
    "rpm": 3000
  },
  "limits": {
    "maxConcurrency": 500,
    "maxRpm": 3000
  }
}

Você enviou requests demais no último minuto. Aguarde o período de retryAfter antes de enviar mais.

503: Concorrência Excedida

{
  "error": "Service at capacity",
  "status": 503,
  "service": "proxy",
  "retryAfter": 2,
  "current": {
    "concurrency": 500,
    "rpm": 1200
  },
  "limits": {
    "maxConcurrency": 500,
    "maxRpm": 3000
  }
}

Muitos requests estão em execução simultaneamente. Alguns de seus requests anteriores ainda não foram concluídos.

Serviço Desativado

Quando um serviço é temporariamente retirado do ar para manutenção, a API retorna 503 com uma mensagem de erro diferente:

{
  "error": "Service disabled",
  "status": 503,
  "retryAfter": 60
}

Isso 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 geralmente é resolvido em poucos minutos.

Não confunda isso com o 503 de concorrência. Uma response "Service disabled" não incluirá os campos current ou limits.

Campos da Response

Lidando com Rate Limits

Use o campo retryAfter para implementar backoff:

import requests
import time

def fetch(url, max_retries=5):
    for attempt in range(max_retries):
        resp = requests.post(
            "https://eu.api.foura.ai/api/single/",
            headers={
                "X-API-Key": "YOUR_API_KEY",
                "Content-Type": "application/json"
            },
            json={"method": "GET", "url": url}
        )

        if resp.status_code in (429, 503):
            data = resp.json()
            wait = data.get("retryAfter", 5)
            time.sleep(wait)
            continue

        return resp

    raise Exception("Max retries exceeded")

Dicas

• Verifique os campos current nas responses de rate limit para entender seus padrões de uso.
• Se você estiver atingindo constantemente os limites de concorrência, reduza o número de requests paralelos.
• Se você estiver atingindo os limites de RPM, adicione um pequeno atraso entre os requests ou agrupe-os em uma janela de tempo maior.
• O valor de retryAfter varia de acordo com o tipo de limite: 2 segundos para concorrência, 5 segundos para RPM.
• Uma response "Service disabled" significa que há uma manutenção em andamento. Não continue sobrecarregando o endpoint.

Relacionado

• API Endpoints: Referência completa de parâmetros
• Error Handling: Todos os tipos de erro e responses
• Troubleshooting: Problemas comuns e correções