O vendor tem o dado; o seu tier pode não expor no endpoint que você chama

Verificar que o vendor tem o dado parece diligência suficiente. A página de preços lista o campo, a documentação traz um exemplo de resposta, o plano cabe no orçamento. Você assina, provisiona a chave e escreve o cliente HTTP.

Só que "o vendor tem o dado" e "o tier que eu comprei expõe esse dado no endpoint que o meu código vai chamar" são duas afirmações diferentes. A segunda é a que paga a conta, e ela costuma aparecer depois que já existe pipeline apostando na primeira. No Marketing_Automation — FastAPI, Celery, OpenAI e Gemini, com o Buffer no fim da esteira como canal de agendamento — a REST v1 do Buffer estava documentada em toda parte. O endpoint tinha migrado para GraphQL em silêncio. O código estava certo contra a documentação e errado contra o serviço.

Antes de provisionar a próxima chave, a pergunta prática é outra: o que dá para descobrir com uma chamada só?

"O vendor tem o dado" não é a pergunta certa

A pergunta certa carrega o plano e a URL dentro dela: o tier que eu assinei entrega esse dado no endpoint que o meu código vai chamar? Parecem a mesma pergunta. Não são — e a diferença entre as duas queima semanas de integração.

No Solo_Trader — Python, Postgres, polars e SQLAlchemy, com a EODHD como fonte de mercado — dois endpoints carregam informação de base relacionada: Fundamentals e Calendar. Pelo nome, parecem dois rótulos para o mesmo conteúdo. São SKUs distintos: URL diferente, nomes de campo diferentes e, o que mais pesa, modelo de consulta diferente. Um responde por símbolo. O outro varre uma janela de data.

Escolher entre os dois não quebra nada. O pipeline roda, os dados chegam, e a diferença fica na conta de chamadas: 500 contra 36 para cobrir a mesma coisa. Esse é o formato típico do erro: não uma exceção estourando no log, e sim um custo silencioso. Alguém percebe na terceira semana, quando pergunta por que a cota já acabou.

O aviso de que o SKU mudou não chega pelo changelog

Três vendors, três maneiras diferentes de a integração parar de funcionar sem que uma linha de código estivesse errada.

O Pollinations.ai era gratuito quando entrou no projeto e virou pago no meio do desenvolvimento. O código continuou idêntico; o que caiu foi o pressuposto econômico daquela etapa.

O Buffer manteve a REST v1 na documentação pública e moveu o endpoint para GraphQL sem alarde. Quem a seguiu ficou certo no papel e errado na chamada.

A Meta cobrou o preço mais alto dos três: a detecção de fraude travou a conta durante a criação de uma Página no Facebook e deixou o Instagram bloqueado por 72 horas. Nenhum dos três avisos chegou como teste vermelho ou como e-mail de changelog lido a tempo. Chegaram como resposta HTTP esquisita, em dia de prazo.

402 e 403 dizem "SKU errado" antes de dizerem "chave errada"

O reflexo diante de um erro de autorização é mexer na credencial. Revoga, gera de novo, cola no arquivo de configuração, reinicia, testa. Meia hora, às vezes uma tarde inteira — e a chave estava boa desde o começo.

Mudei a ordem da investigação depois da segunda vez que isso me pegou. Hoje leio 402 e 403 primeiro como "este endpoint não está no meu plano" e só depois como "esta chave está inválida". O teste custa pouco: pegue outro endpoint do mesmo vendor, um que você sabe que está incluso, e chame com a mesma chave. Se responde, a credencial está viva e o problema é o SKU.

Uma chamada de teste antes do pipeline inteiro

Duas etapas resolvem quase toda essa família de problemas. A primeira é ler a documentação do vendor atrás do nome exato do endpoint antes de provisionar qualquer chave: capacidade antes de credencial. A segunda é o smoke probe — uma chamada contra o endpoint real, com a chave real, no tier real, antes de escrever qualquer linha que dependa do formato da resposta.

Recomendo as duas, e elas cobram. Uma chamada extra na cota, algum tempo de preparo antes de qualquer resultado visível na tela, e a disciplina de não pular a etapa justamente no dia de prazo apertado — que é exatamente o dia em que a vontade de pular é maior. Esse é o preço de fazer. O preço de não fazer é descobrir a divergência com semanas de pipeline construído em cima do endpoint errado, e esse eu já paguei.

A regra que sustento hoje é rígida de propósito: nenhuma chave nova entra em produção sem uma chamada de teste contra o endpoint real antes dela. Abro exceção no dia em que um vendor publicar, por tier, a lista exata dos endpoints inclusos — e mantiver essa lista de pé. Pollinations, Buffer, Meta, EODHD: nenhum dos quatro fez isso.