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.
Limites de taxa devem ser documentados, não descobertos
Existe um tipo específico de manhã ruim que começa com um pico de requisições com falha e termina com um desenvolvedor lendo a página de status de um provedor pela primeira vez, tentando descobrir se as falhas são uma indisponibilidade ou um limite que ele nunca soube que existia. Essa manhã é totalmente evitável, e o fato de ela ainda acontecer neste setor é uma falha de documentação, não de infraestrutura.
Um limite de taxa não é segredo. É um fato operacional sobre um sistema, assim como um tamanho máximo de requisição ou um método HTTP suportado, e pertence ao mesmo lugar: por escrito, antes que alguém o atinja. Publicamos os nossos na documentação de limites de taxa, junto com as páginas de autenticação e de erros, para que os números com os quais um desenvolvedor precisa planejar estejam disponíveis antes de ele escrever a primeira linha de código de integração, e não depois da primeira tarde com cara de indisponibilidade.
Mas só a documentação não basta, porque os limites podem depender do plano em que você está, e um documento fica desatualizado no momento em que o status da sua conta muda. É por isso que cada resposta também traz cabeçalhos de cota em tempo real: o seu limite, quanto você já usou, quanto resta da cota gratuita, quanto da cota compartilhada da sua rede já foi usado, o seu crédito pré-pago restante e quando a cota será reiniciada. Você não precisa comparar um documento com o seu painel para saber onde está. A resposta vem junto com a própria resposta da API, em cada chamada.
Alguns provedores tratam limites publicados como uma fraqueza competitiva a esconder, com a teoria de que um número visível convida os clientes a negociá-lo para baixo ou a compará-lo com um concorrente. Achamos que esse instinto está invertido. Um limite que ninguém consegue ver não protege a infraestrutura do provedor nem um pouco melhor. Só significa que a primeira vez que um cliente descobre o número real é quando já o ultrapassou, no pior momento possível para um produto em crescimento, diante dos seus próprios usuários.
Documentar os limites desde o início também impõe uma disciplina de design ao provedor. Se um limite de taxa vai ser publicado, ele precisa ser um número real que alguém esteja disposto a sustentar, e não um limite interno vago que é ajustado discretamente sempre que se torna inconveniente. Escrever o número e colocá-lo nos cabeçalhos de resposta de cada chamada significa que o limite precisa realmente ser o limite, de forma consistente, que é exatamente a propriedade de que um desenvolvedor precisa.
Descobrir um limite de taxa por meio de uma requisição com falha em produção não é um rito de passagem. É um sinal de que a documentação não cumpriu o seu papel. A nossa existe para que essa manhã ruim seja algo sobre o qual você lê acontecendo com outra pessoa, e não algo que acontece com você.