RateLimit e RateLimit-Policy versus X-RateLimit-*: como ler os cabeçalhos de cota que uma API envia

O que é

O RFC 9110 define um único cabeçalho padronizado e essencial para esse fim: "the Retry-After field value can be either an HTTP-date or a number of seconds to delay after receiving the response" (o valor pode ser uma data HTTP ou um número de segundos de espera após receber a resposta), formalmente Retry-After = HTTP-date / delay-seconds. O RFC 9110 descreve seu significado em respostas 503 e 3xx, e o RFC 6585 permite incluí-lo em uma resposta 429. Ele indica por quanto tempo o cliente "ought to wait" (deveria esperar): é o número do próprio servidor, não uma estimativa feita pelo cliente. Além disso, um Internet-Draft ativo do IETF, draft-ietf-httpapi-ratelimit-headers (revisão -11 no momento da escrita), propõe dois campos de caráter consultivo, para uso antes de uma requisição ser limitada: RateLimit-Policy, que descreve a cota (por exemplo, RateLimit-Policy: "default";q=100;w=60, ou seja, 100 requisições por janela de 60 segundos sob uma política chamada "default"), e RateLimit, que informa a cota atualmente disponível sob essa política (por exemplo, RateLimit: "default";r=50;t=30: 50 unidades de cota disponíveis, para serem usadas dentro de uma janela efetiva de 30 segundos). O rascunho avisa que a janela efetiva "does not imply anything about when the server will increase the available quota" (não diz nada sobre quando o servidor aumentará a cota disponível); portanto, t não é um timestamp de reinício da cota. Isso ainda é um rascunho: pelo processo do IETF, um Internet-Draft é "valid for a maximum of six months" (válido por no máximo seis meses) e não deve ser citado como referência estável, de modo que a sintaxe exata dos campos ainda pode mudar antes da publicação. Na prática, a maioria das APIs em produção é anterior a esse rascunho ou o ignora e envia cabeçalhos próprios, com nomes como x-ratelimit-limit, x-ratelimit-remaining e x-ratelimit-reset (a API REST do GitHub é um exemplo documentado), em um formato que o rascunho não regula e que varia de fornecedor para fornecedor.

Por que importa

Um cliente genérico que se integra a muitas APIs vai encontrar as três situações: um cabeçalho consultivo em processo de padronização, um cabeçalho ad hoc específico do fornecedor, ou nada além de Retry-After na 429 final. Por isso, ele precisa de uma ordem de fallback que não presuma a presença de nenhum deles.

Como aplicar

• Trate Retry-After como autoridade sempre que estiver presente, em qualquer código de status que o traga; interprete as duas formas (segundos inteiros e HTTP-date) e espere pelo menos esse tempo antes de tentar de novo.
• Se RateLimit e RateLimit-Policy estiverem presentes, faça o parsing de forma defensiva (são um rascunho: nomes de campos, delimitadores e até os nomes dos cabeçalhos mudaram entre as revisões) e use-os para reduzir o ritmo antes que a cota chegue a zero.
• Se aparecerem apenas cabeçalhos específicos do fornecedor no estilo x-ratelimit-*, considere que sua presença e seu significado valem somente para aquela API; não presuma que os mesmos nomes de campo signifiquem a mesma coisa em outro provedor.
• Quando nenhum dos itens acima aparecer, recorra a backoff exponencial com jitter em 429/503, já que o RFC 9110 não exige nenhum cabeçalho consultivo.

Armadilhas

Fixar no código um parser para a sintaxe atual do rascunho de RateLimit e RateLimit-Policy e tratá-la como um padrão finalizado; o próprio rascunho alerta contra citá-lo "as reference material... other than as work in progress." (como material de referência, exceto como trabalho em andamento). Ignorar um valor de Retry-After porque um cabeçalho consultivo sugeria que ainda restava cota: Retry-After reflete o que o servidor de fato decidiu, o que pode diferir de uma estimativa consultiva enviada antes.