Rate limit, retry, idempotência e secrets

Fecha o Módulo 6 com o que torna qualquer integração robusta — os quatro padrões que valem pra Anthropic, Resend, Google e qualquer terceiro que vier. É a parte sem glamour que separa integração de brinquedo de integração de produção. E é onde vibe coding mais precisa de um humano por perto.

1. Secrets: a regra nº1

Chave de API nunca no código. Sempre em variável de ambiente, fora do versionamento. No ClubPetro, cada integração tem suas envs (Anthropic, Resend, Google, Evolution…), e o repo nunca carrega segredo.

• Secret commitado é vazamento — e segredo que vazou está vazado pra sempre, mesmo que você apague depois.
• Atenção redobrada com IA: revise pra ela nunca logar ou hardcodar uma chave "pra testar".
• Em produção (Cloud Run, Módulo 7), secret entra por mecanismo de secret, não por env solta — e tem armadilha conhecida nossa de deploy que apaga secret se feito errado.

2. Rate limit: respeite a cota alheia

Todo terceiro limita quantas chamadas você faz. Estourar o limite = erro, ou conta bloqueada. Os padrões:

• Paginação ao puxar muito dado.
• Throttle pra não disparar tudo de uma vez.
• Backoff quando o terceiro responde "calma" (429).

3. Retry: falha de rede é normal

Tudo que sai pela rede falha às vezes. Retry com backoff transforma soluço em não-evento. Mas — como martelamos no Módulo 4 — retry exige idempotência, senão você multiplica efeito colateral (e-mail duplicado, cobrança dobrada).

4. Idempotência: rodar duas vezes = rodar uma

A propriedade mais subestimada. "Enviar e-mail", "criar registro", "cobrar" precisam ser seguros pra repetir. Use chave de idempotência, upsert, checagem de "já feito". É o que torna retry seguro e o que respeita a regra da casa: antes de criar dado, veja se já existe.

O quinto, implícito: degradação graciosa

Terceiro caiu? A feature degrada, a plataforma não cai. Abstraia o cliente do terceiro num módulo nosso pra isolar a dependência — quando o de fora falha, o estrago fica contido.

Por que isso é o coração de vibe coding maduro

A IA escreve o "caminho feliz" da integração em segundos. Estes quatro padrões são o caminho infeliz — e é nele que produto real vive ou morre. A IA não pensa neles sozinha; você exige. É exatamente a fronteira entre acelerar com IA e terceirizar julgamento.

⚠️ Armadilha #37: aceitar a integração da IA só porque o caminho feliz funciona. Sem rate limit, retry, idempotência e secret protegido, ela funciona na demo e explode em produção — geralmente no pior dia.

Fim do Módulo 6 — APIs de Terceiros. Próximo: Módulo 7 (#38) — CI/CD e AI Code Review no GitHub.