6 problemas que seu API Gateway está sofrendo

Um API Gateway parece um proxy fino até a noite em que vira o outage. Centralizar é o objetivo: um lugar para TLS, autenticação, rate limit, roteamento e políticas. Centralizar também é o risco: toda requisição compartilha o mesmo orçamento finito de event loop, pools de conexão e raio de explosão.

O padrão Gateway Offloading da Microsoft deixa isso claro: mantenha o gateway altamente disponível, dimensione-o para não virar gargalo e nunca jogue lógica de negócio nele. O postmortem público da Canva de 12 de novembro de 2024 mostra o que acontece quando essa porta de entrada satura — cerca de 1,5 milhão de requisições por segundo, aproximadamente 3× o pico típico, combinado com um lock de telemetria que esgotou o event loop do Netty até o OOM killer do Linux derrubar a frota.

Este artigo é um checklist diagnóstico de seis problemas que gateways já sofrem em produção — e como corrigi-los antes do próximo thundering herd.

O que um API Gateway é (e o que não é)

Um API Gateway é a fachada de borda na frente de um ou mais backends. Funções típicas: terminar TLS, autenticar chamadores, aplicar cotas, rotear por path ou header, emitir métricas e traces e, opcionalmente, transformar headers ou paths.

Ele não substitui:

• Autorização por serviço com contexto de domínio
• Composição de BFF que entende telas de produto
• Retries ilimitados que escondem sobrecarga sistêmica
• Um depósito de “só mais um plugin” até o hot path bloquear

Se você o trata como um cano passivo, perde os modos de falha. Se o trata como servidor de aplicação, inventa modos novos.

Problema 1 — Raio de explosão compartilhado e saturação

Sintoma: O site está “fora” mesmo com a maioria dos backends saudáveis. O autoscaling sobe capacidade que morre assim que fica healthy.

Por que acontece: Um cluster de gateway na frente de tudo. Um pico, uma chamada bloqueante no event loop ou pressão de memória leva a API pública inteira junto. A Microsoft alerta explicitamente para evitar pontos únicos de falha e impedir que o gateway vire o gargalo.

O outage da Canva é o caso de referência. Um atraso no caminho do CDN enfileirou mais de 270 mil clientes em um asset. Quando o asset chegou, os clientes retomaram e bateram no API Gateway com um rebanho sincronizado. Os load balancers abriram mais conexões para tasks já sobrecarregadas. A memória off-heap cresceu; o OOM killer limpou containers mais rápido do que o autoscaling conseguia repor. A mitigação só funcionou depois que o tráfego foi bloqueado no CDN, para as tasks novas subirem a frio.

O que fazer:

• Aumentar capacidade base e folga de memória; fazer load test do gateway como serviço tier-0
• Adicionar load shedding (rejeitar cedo com 503) antes que filas consumam a frota
• Isolar domínios de falha (gateways ou listeners separados por superfície de produto) para um rebanho não tomar todas as tasks
• Manter um runbook ensaiado para derrubar ou restaurar tráfego no CDN / edge, não só dentro do cluster

Saturação não é “o gateway está lento”. É “o gateway é o gargalo do produto”.

Problema 2 — Orçamento de timeout quebrado

Sintoma: Clientes veem 504 / requisições abandonadas enquanto o gateway ainda segura trabalho upstream. Pools de conexão enchem. A latência sobe e depois tudo falha junto.

Por que acontece: Timeouts são definidos uma vez e esquecidos. Se o gateway espera tanto quanto (ou mais que) o cliente, você gasta concorrência do gateway em requisições que o usuário já abandonou. Upstreams lentos enchem pools; filas pendentes crescem; trabalho novo é rejeitado enquanto backends continuam sobrecarregados — um loop que se reforça.

A AWS documenta o limite duro dessa classe de falha no Amazon API Gateway: quando a integração ultrapassa a espera máxima configurada, o chamador recebe HTTP 504 (“Endpoint request timed out”). O timeout padrão de integração por muito tempo foi 29 segundos em muitos setups REST; desde junho de 2024 a AWS permite aumentá-lo para APIs REST Regionais e privadas (muitas vezes com trade-off de cota de throttle). Subir o teto sem consertar a hierarquia só mantém zumbis vivos por mais tempo.

O que fazer:

timeout do cliente  >  timeout gateway→upstream  >  timeout por tentativa

• Faça timeouts gateway→backend estritamente menores que cliente→gateway
• Limite filas de pending requests; prefira 503 cedo a uma espera de 30 segundos que falha de qualquer jeito (o Envoy rastreia max_pending_requests por isso)
• Propague um deadline (tempo absoluto) para serviços aninhados falharem rápido quando o orçamento já acabou
• Para trabalho longo, não estique o caminho síncrono do gateway — use padrões assíncronos (fila + status) em vez de “só aumentar o timeout”

Veja também a referência sobre timeouts, retries, jitter e backoff.

Problema 3 — Tempestade de retries sem budget

Sintoma: A taxa de erro do upstream sobe e, de repente, multiplica. CPU do gateway e QPS do upstream sobem juntos. A recuperação demora mais que a falha original.

Por que acontece: Retry é egoísta: gasta mais tempo do servidor para melhorar a taxa de sucesso sua. O AWS Well-Architected REL05-BP03 aponta retries sem backoff, jitter e teto — e especialmente retries em várias camadas que se somam numa tempestade. A documentação do Envoy diz o mesmo em termos de gateway: limite retries em voo para falhas esporádicas ainda puderem ser retentadas, sem o volume explodir em falha em cascata. Prefira um retry budget (a orientação padrão costuma girar em torno de cerca de 20% do tráfego ativo + pendente como retries concorrentes) a um max_retries estático sozinho.

O que fazer:

• Retente só falhas transitórias e idempotentes (erros de connect, timeouts, alguns 5xx / 429) — não 4xx de validação ou auth
• Limite tentativas e deadline total; use backoff exponencial com jitter
• Configure retry budget / máximo de retries concorrentes no cluster (no Envoy, retry_budget sobrescreve circuit breakers estáticos de retry quando definido)
• Retente em um lugar da stack (cliente ou gateway ou mesh) — não nos três
• Combine com circuit breakers e outlier ejection para parar de mandar tráfego pleno a um host morto — e limite max_ejection_percent para um deploy ruim correlacionado não ejetar o cluster inteiro (o Envoy usa teto padrão de 10%)

Problema 4 — O god gateway (lógica de negócio na borda)

Sintoma: Toda mudança de produto exige deploy do gateway. Plugins parseiam corpos JSON, remodelam campos e codificam regras de domínio. Latência e carga cognitiva sobem juntas.

Por que acontece: Offload de preocupações transversais é correto. Offload de lógica de negócio não é. O padrão Gateway Offloading da Microsoft não hesita: “Business logic should never be offloaded to the gateway.” Injeção de headers, rewrites de path em migrações e correlation IDs pertencem à borda. Filtrar campos de resposta por semântica de produto, agregar cinco serviços num “DTO de tela” ou codificar entitlements em plugins Lua/JS duplica o domínio no pior lugar: o hot path compartilhado.

O que fazer:

Mantenha o gateway estruturalmente consciente e semanticamente cego. Se a mudança precisa mais da aprovação de um product owner do que de um SRE, provavelmente não deveria viver na config do gateway.

Problema 5 — Observabilidade cega e trabalho bloqueante no hot path

Sintoma: Os dashboards mostram “API vermelha” sem separar overhead da borda e tempo do upstream. Ou o gateway parece bem até a carga subir — aí uma lib de métricas “inofensiva” trava threads e o throughput despenca.

Por que acontece: Gateways costumam emitir uma taxa de sucesso/erro e parar. Você não sabe se o cliente espera em TLS, plugins, idas e vindas de auth ou no backend. Pior: logging síncrono, introspecção de token em toda requisição ou locks contidos na telemetria rodam no event loop. O postmortem da Canva é explícito: threads do event loop Netty não podem bloquear; um re-registro de telemetria sob lock reduziu o throughput por task exatamente quando o rebanho chegou.

O que fazer:

• Separe overhead do gateway (latência vista pelo cliente menos tempo do upstream) da latência upstream; alerte nos dois
• Acompanhe saúde dos pools upstream: conexões ativas, profundidade de fila pendente, overflows de retry, abertura de circuit breakers (o Envoy expõe contadores como upstream_rq_retry_overflow e overflows de pending)
• Prefira verificação local de JWT com JWKS em cache a introspecção síncrona em toda chamada quando o orçamento de latência é apertado
• Trate telemetria e plugins como código estrutural: sem I/O bloqueante no caminho da requisição; faça load test das cadeias de plugin a 50–80% de capacidade, não só em idle
• Propague um correlation / trace ID de ponta a ponta — gere na borda se faltar

Se você não consegue responder “a borda está doente ou o payments está doente?” em menos de um minuto, esse problema já é seu.

Problema 6 — Hardening fraco da borda e do control plane

Sintoma: Rate limits que parecem certos no papel são buriados com facilidade. Backends são alcançáveis sem o gateway. A Admin / control API está exposta além do que qualquer um pretendia.

Por que acontece: Três lacunas clássicas:

1. Rate limits por nó — contadores em memória em N réplicas viram N limites independentes. Stores compartilhados (por exemplo Redis) consertam o teto global, mas adicionam latência e uma nova dependência; escolha o algoritmo de propósito (token bucket costuma ser o que APIs públicas querem). Sempre devolva 429 com Retry-After (ou equivalente) para o cliente não retentar na hora e amplificar a carga.
2. Bypass do backend — a orientação de gateway da Microsoft lembra que o gateway é o endpoint público: limite o acesso público aos backends para a política não ser contornada.
3. Exposição do control plane — a Kong documenta que a Admin API dá controle total de services, routes, plugins e credenciais. Escutar só em localhost por padrão é intencional; bind em 0.0.0.0:8001 pode “comprometer seriamente a segurança de todo o cluster Kong”. O estudo de caso da Trend Micro sobre misconfigurations do Kong reforça o mesmo ponto: Admin API e acesso ao datastore precisam ficar bem escopados.

O que fazer:

• Enforce authn e throttling grosseiro na borda; coloque backends em redes privadas
• Use contador compartilhado e atômico para rate limits globais quando precisar de um teto verdadeiro no cluster
• Trave Admin / control APIs: localhost ou CIDR privado, ACLs de firewall, authn em qualquer caminho remoto, RBAC onde existir — nunca um bind público casual
• Varra continuamente rotas sombra que pulam o gateway

O data plane só é tão confiável quanto o control plane que o configura.

Como os seis problemas se reforçam

pico / deploy / blip de CDN
        │
        ▼
   saturação (1)  ←── telemetria / plugins bloqueantes (5)
        │
        ├── timeouts quebrados (2) → esgotamento de pool
        ├── retries sem teto (3) → carga ×N
        └── trabalho de god-gateway (4) → menos folga
                │
                ▼
        lacunas de controle (6) → bypass ou tráfego sem shedding

Corrigir só retries enquanto o event loop bloqueia — ou só HA com timeouts invertidos — deixa o amplificador intacto.

Perguntas frequentes

Um API Gateway é sempre um single point of failure?

Ele é um domínio de falha compartilhado, a menos que você invista em redundância, isolamento e shedding. Várias instâncias atrás de um load balancer removem um processo único como SPOF, mas uma config compartilhada, um bug de telemetria ou um rebanho global ainda podem derrubar o produto — como a Canva mostrou. Trate a disponibilidade do gateway como requisito de produto, não como checkbox.

O gateway deve retentar por mim?

Às vezes, para GETs idempotentes e erros transitórios seguros — com budget. Prefira uma camada de retry. Retries no gateway empilhados em retries de cliente e de mesh são um caminho comum para tempestades (AWS REL05-BP03).

Gateway vs BFF vs service mesh — quem faz o quê?

• Gateway: política north-south na borda (TLS, authn, limites grosseiros, roteamento)
• BFF: agregação no formato do produto e contratos orientados à UI
• Mesh: resiliência east-west (timeouts, retries, mTLS entre serviços)

Sobreposição é aceitável; duplicar retry + authz nos três não é.

Como sei que a hierarquia de timeout está errada?

Se você vê trabalho upstream terminando depois que o cliente desconectou, filas pendentes crescendo sob backends lentos, ou 504 frequentes enquanto integrações ainda rodam além da paciência do cliente, o orçamento está invertido ou ausente. Meça timeout do cliente, timeout do gateway e duração do upstream no mesmo trace.

Conclusão

Seu API Gateway já está sob pressão em seis frentes: saturação compartilhada, timeouts invertidos, retries sem budget, lógica de domínio na borda, observabilidade opaca ou bloqueante, e hardening frouxo dos planos de dados e controle. Nada disso é teórico — aparece em docs de vendors, padrões de arquitetura e postmortems públicos.

Escolha uma rota de produção nesta semana. Verifique a hierarquia de timeouts, confirme que retries têm budget em uma única camada, meça o overhead do gateway separado do tempo upstream e confirme que redes de Admin e backend não contornam a política. O objetivo não é um god-proxy mais inteligente. É uma borda entediante, com shedding e observável, que falha em pedaços pequenos em vez de levar o produto junto.

Referências

1. Canva incident report: API Gateway outage — Canva Engineering (dez. 2024)
2. Gateway Offloading pattern — Microsoft Azure Architecture Center
3. API gateways in microservices — Microsoft Azure Architecture Center
4. Gateway Routing pattern — Microsoft Azure Architecture Center
5. Circuit breaking — documentação do Envoy Proxy
6. Outlier detection — documentação do Envoy Proxy
7. Circuit breakers (proto) — retry_budget — API do Envoy Proxy
8. REL05-BP03 Control and limit retry calls — AWS Well-Architected
9. REL05-BP05 Set client timeouts — AWS Well-Architected
10. Troubleshoot API Gateway HTTP 504 timeout errors — AWS re:Post
11. Amazon API Gateway integration timeout limit increase beyond 29 seconds — AWS News (jun. 2024)
12. Secure the Admin API — documentação do Kong Gateway
13. Kong API Gateway Misconfigurations: An API Gateway Security Case Study — Trend Micro
14. Timeouts, retries, and backoff with jitter — Amazon Builders’ Library
15. Exponential Backoff And Jitter — AWS Architecture Blog