Políticas de tráfego e limites

A política de tráfego reúne três controles que valem para a API inteira: limite de taxa, CORS e limite de corpo.

Limite de taxa

O limite protege o seu backend e mantém a API disponível para todos: cada escopo tem um número máximo de requisições dentro de uma janela de tempo. Acima disso, a resposta é 429.

A política aceita três escopos independentes, cada um com limit e window_seconds:

Escopo	Campo	Conta por
API	rate_limits.per_api	a API inteira, somando todos os consumidores e IPs
Consumidor	rate_limits.per_consumer	cada consumidor autenticado
IP	rate_limits.per_ip	endereço IP real do cliente

Campo	Faixa
limit	1 a 1 000 000 de requisições
window_seconds	1 a 86 400 segundos (24 h)

Os três podem ser combinados: a requisição é recusada se qualquer um estourar.

curl -sS -X PUT "$BASE/v1/apis/$API_ID/traffic-policy" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
        "rate_limits": {
          "per_api":      {"limit": 10000, "window_seconds": 60},
          "per_consumer": {"limit": 600,   "window_seconds": 60},
          "per_ip":       {"limit": 120,   "window_seconds": 60}
        }
      }'

Uma rota pode sobrescrever o limite por API (rate_limit_override). Quando ela faz isso, a regra por API deixa de valer para aquela rota e passa a valer a regra própria, contada por rota. As regras por consumidor e por IP continuam valendo.

Semântica da janela

• A janela é fixa de window_seconds: o contador começa quando a primeira requisição do período é contada e reinicia no fim da janela. Não é uma média móvel.
• Os contadores ficam num armazenamento compartilhado, então o limite vale para o conjunto das máquinas do gateway, não por máquina.
• O contador por consumidor só existe quando há consumidor identificado — em API PUBLIC ou em modo JWT_OIDC, a regra por consumidor não afeta a requisição.
• O contador por IP usa o IP real do cliente, obtido do protocolo do balanceador. Se a cadeia não informar o IP real, todos os clientes passam a contar como o mesmo endereço — e um limite "por IP" vira um limite global.

O que o cliente recebe

Situação	Resposta
Dentro do limite	a resposta normal do backend
Fora do limite	429 com a mensagem rate_limited

Recomendação: trate pelo status 429 e por Retry-After quando presente, não pelo nome de um cabeçalho de cota.

Se o armazenamento de contadores falhar

Decisão explícita do produto: a API continua atendendo. Com o armazenamento de contadores fora:

• o limite deixa de valer (não há onde contar);
• a latência sobe pelo tempo de espera do armazenamento (curto, 200 ms por padrão);
• a API não cai e não devolve 500.

O raciocínio: derrubar todas as APIs por causa de um componente auxiliar de contagem é pior do que ficar sem limite por alguns minutos.

Quando usar cada escopo

Cenário	Configuração recomendada
API interna, poucos consumidores	per_consumer apenas
API pública na Internet	per_ip (proteção contra abuso) e per_api (proteção do backend)
Plano gratuito e plano pago	per_consumer (o consumidor identifica o plano) com per_ip como piso
Rota pesada (relatório, exportação)	per_api com rate_limit_override na rota, com limite menor

Limites do próprio recurso

• Não há limite de "rajada" (burst) configurável separadamente: o 429 vem da contagem na janela.
• Não há cota por plano comercial. O produto mede uso, mas não aplica preço.
• Publicar uma nova revisão que altera os limites não zera os contadores em curso: a chave de contagem é o escopo (a API, o consumidor, o IP), não o valor do limite.

CORS

CORS (Cross-Origin Resource Sharing) é o que permite que uma página web em outro domínio chame a sua API pelo navegador. O gateway responde ao preflight e acrescenta os cabeçalhos de CORS, sem precisar que o seu backend faça isso.

Campo cors da política de tráfego:

Campo	Padrão quando vazio	Regra
allow_origins	*	* ou https://host[:porta] — nunca http://, nunca caminho, nunca credencial na URL
allow_methods	* (ou a lista padrão, com credenciais)	métodos permitidos
allow_headers	* (ou a lista padrão, com credenciais)	cabeçalhos permitidos no pedido
expose_headers	X-Request-Id	cabeçalhos de resposta que o JavaScript pode ler
allow_credentials	false	permite cookies e credenciais do navegador
max_age_seconds	5	0 a 86400 — por quanto tempo o navegador guarda o resultado do preflight

Regras de origem

• Só https. http:// é recusado com 400 cors_insecure.
• Sem caminho: https://app.suaempresa.com vale; https://app.suaempresa.com/painel não.
• Sem usuário e senha na URL.
• Até 64 origens por API.
• * junto com allow_credentials: true é recusado (400 cors_insecure com reason = cors_wildcard_with_credentials): o navegador aceitaria a combinação, mas ela exporia a API a qualquer site que o usuário esteja visitando, com os cookies dele.

curl -sS -X PUT "$BASE/v1/apis/$API_ID/traffic-policy" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
        "cors": {
          "allow_origins": ["https://app.suaempresa.com"],
          "allow_methods": ["GET", "POST", "OPTIONS"],
          "allow_headers": ["Content-Type", "X-API-Key"],
          "expose_headers": ["X-Request-Id"],
          "allow_credentials": false,
          "max_age_seconds": 600
        }
      }'

Efeito no tráfego

• O preflight (OPTIONS) é respondido pelo gateway; o seu backend não precisa tratá-lo.
• Com allow_credentials: true, o navegador exige que a origem seja explícita (sem *) e que a API responda Access-Control-Allow-Credentials: true.
• Se a origem não estiver na lista, o navegador bloqueia a leitura — a requisição pode até chegar ao backend, mas o JavaScript não vê a resposta. Não use CORS como mecanismo de autorização: quem não é navegador ignora CORS completamente. Para isso existem API_KEY e JWT_OIDC.

Limitações de CORS

• Não há suporte a origem com curinga parcial (https://*.suaempresa.com). A lista é explícita.
• CORS é aplicado no serviço da API, então vale para todas as rotas dela.
• CORS não é cacheado no gateway: cada preflight é respondido na hora.

Limite de corpo

max_body_bytes define o tamanho máximo do corpo da requisição, de 1 byte a 104 857 600 bytes (100 MiB). Acima do limite, a resposta é 413.

O valor é aplicado no serviço da API, então vale para todas as rotas dela.

Erros comuns

Resposta	Causa	Ação
400 cors_insecure (cors_origin_scheme)	origem http://	use https://
400 cors_insecure (cors_origin_path)	origem com caminho	informe só esquema, host e porta
400 cors_insecure (cors_wildcard_with_credentials)	* com allow_credentials: true	liste as origens, ou desligue credenciais
400 validation_error (cors_too_many_origins)	mais de 64 origens	consolide (uma origem por domínio)
400 validation_error (rate_limit_override_incomplete)	rate_limit_override sem limit ou sem window_seconds	envie os dois campos

Próximos passos

• Rotas: rate_limit_override e timeout_override_ms por rota.
• Uso e métricas: como observar 429 e latência.
• Erros e diagnóstico: too_many_requests na administração e 429 no tráfego.