Recuar como cliente: Retry-After, cabeçalhos RateLimit e orçamentos por host

Objetivo

Manter-se dentro dos limites de um servidor sem adivinhar, recuperar de um limite atingido sem agravar a situação e evitar que as muitas requisições pequenas de um agente se transformem numa indisponibilidade do serviço ou no bloqueio da chave.

Pré-requisitos

Um cliente capaz de inspecionar códigos de status e cabeçalhos, de esperar (sleep) e de guardar um pequeno estado por host. É preciso saber quais requisições são idempotentes.

Passos

1. Ao receber 429 Too Many Requests (RFC 6585) ou 503 Service Unavailable, procure o cabeçalho Retry-After. A RFC 9110 o define como um número de segundos ou uma data HTTP; espere esse tempo e tente de novo uma única vez. O Retry-After é uma instrução do servidor e prevalece sobre qualquer agendamento local.
2. Sem Retry-After, recue de forma exponencial a partir de um atraso base, com jitter total (full jitter), limite o atraso máximo e limite o número de tentativas. Conte as tentativas por requisição, não por sessão, e desista com um erro claro quando o limite for atingido.
3. Leia os cabeçalhos consultivos quando existirem. O rascunho do IETF sobre os campos de cabeçalho RateLimit define um campo RateLimit, que indica a cota restante e os segundos até a reposição, e um campo RateLimit-Policy, que descreve a política de cota; um cliente que os leia pode desacelerar antes do primeiro 429. Trate-os como indicações que podem estar ausentes ou mudar de formato de servidor para servidor, e recorra ao passo 2 nesses casos.
4. Mantenha um orçamento por host e por credencial: um número máximo de requisições em andamento e um intervalo mínimo, reduzidos a cada 429 e aumentados apenas lentamente. Agentes paralelos que compartilham a mesma chave compartilham o mesmo orçamento; coordene-os por meio de um contador compartilhado ou de uma fila, em vez de cada um recuar de forma independente.
5. Nunca repita às cegas uma escrita não idempotente. Anexe uma chave de idempotência quando a API a suportar, para que uma nova tentativa após um timeout não duplique o efeito; caso contrário, verifique se o efeito já ocorreu antes de repetir.
6. Registre em log cada 429 com o host, a classe do endpoint e a espera aplicada; um padrão de 429 num mesmo endpoint é um sinal de design (buscar menos, usar mais cache, usar um endpoint em lote), não um motivo para aumentar o limite de tentativas.
7. Prefira requisições condicionais e cache nas leituras: um 304 Not Modified é barato para ambos os lados e, em geral, não conta para a cota da mesma forma que uma resposta completa, embora essa seja uma política que cabe ao servidor indicar.

Resultado esperado

Os limites atingidos tornam-se raros e autocorretivos, as novas tentativas nunca duplicam uma escrita e o serviço vê um cliente que desacelera quando solicitado, em vez de um que insiste com mais força.

Limites e base de verificação

Síntese de padrões e proposta de disciplina para o cliente; não há medições. O rascunho dos cabeçalhos RateLimit é apenas um rascunho: os nomes dos campos e a semântica podem mudar até a publicação, e muitos servidores enviam, em vez deles, cabeçalhos próprios de cada fornecedor.