O problema das chaves de API que nunca expiram
Uma chave emitida anos atrás, nunca trocada e ainda válida hoje não é uma conveniência. É um risco que ninguém examina de verdade há anos.
Por que publicamos nossos códigos de erro em vez de escondê-los
Uma requisição de API com falha já é um momento ruim no dia de alguém. Fica pior quando o código de erro retornado não é explicado em lugar nenhum, e o desenvolvedor que está depurando precisa adivinhar se um 400 significa um parâmetro malformado, um campo obrigatório ausente ou algo totalmente diferente que por acaso compartilha o mesmo código de status com outros três problemas sem relação. Um erro não documentado não é apenas um incômodo. Ele transforma uma correção de cinco minutos em uma investigação sem fim, às vezes terminando em um chamado de suporte que poderia ter sido evitado com a leitura de uma página que deveria existir.
Publicamos nossos códigos de erro com clareza na documentação de erros, listando o que cada um realmente significa e o que costuma causá-lo, junto com as páginas de autenticação e de limites de taxa, que descrevem as outras formas pelas quais uma requisição pode falhar. O objetivo é que, quando algo der errado, a resposta esteja a uma página de distância, e não seja um palpite baseado em convenções gerais de códigos de status HTTP que podem ou não corresponder exatamente ao que o nosso sistema fez.
Esconder detalhes de erros, mesmo sem intenção, por meio de uma documentação rasa, às vezes nasce de um instinto que parece razoável: expor exatamente por que uma requisição falhou poderia, em teoria, ajudar alguém que esteja sondando uma API em busca de fraquezas. Na prática, essa preocupação raramente se sustenta diante do custo real. A esmagadora maioria das pessoas que encontram um código de erro são desenvolvedores legítimos tentando corrigir a própria integração, e não adversários mapeando uma superfície de ataque. Otimizar a documentação de erros em função do raro mal-intencionado, à custa da clareza para todos os outros, inverte a relação de custo e benefício.
Publicar códigos de erro com clareza também traz um benefício de disciplina de design: obriga à consistência interna. Se cada código de erro precisa ser documentado com uma explicação simples, fica muito mais difícil acumular uma pilha de condições de erro improvisadas e sobrepostas que só o engenheiro que as escreveu entende por completo. Escrever a documentação também é, discretamente, uma forma de revisão de código do próprio tratamento de erros, porque um erro difícil de explicar com clareza costuma ser sinal de que a condição por trás dele não foi bem pensada desde o início.
Falhas relacionadas à cota recebem um tratamento parecido, por meio de cabeçalhos de resposta e não apenas de códigos de erro. Toda resposta traz o limite da sua cota, o uso, a cota gratuita restante, o uso da rede, o crédito restante e o horário de redefinição, então uma requisição que falha por causa da cota não é, de forma alguma, um código de status misterioso. É um número que você poderia ter verificado antes de enviar a requisição, e que pode ler diretamente na resposta que falhou.
Nada disso elimina a frustração de uma requisição com falha. Significa apenas que a frustração deve terminar na documentação, com uma resposta de verdade, em vez de continuar em uma fila de suporte ou em um jogo de adivinhação por posts antigos de fóruns sobre o que um código de status de uma API totalmente diferente poderia ter significado em uma situação parecida.