Gerir os limites de débito

01Em uma frase #sec_56b85c74

Três contadores independentes governam o débito — os dados, as provas, os tokens — e certos pedidos consomem dois de uma vez.

02Os três tetos #sec_0a236919

São valores por defeito, não constantes: a sua subscrição pode ter um teto mais elevado. Um aumento concedido pelo editor tem efeito a partir do pedido seguinte, sem reinício nem atraso de propagação.

03O contador das provas adiciona-se, não substitui #sec_4b9c7978

Este é o ponto que mais surpreende. Um pedido a evidence decrementa os dois contadores: o das provas e o standard. Um cliente que só fizesse pedidos de provas seria, portanto, interrompido a sessenta por minuto, não a seiscentos.

A razão é mensurável: cada pedido de prova produz um PDF e assina-o, ou seja, cerca de 325 ms de processador e criptografia. No teto comum, um único cliente teria consumido quase 40% da máquina; a sessenta por minuto, cerca de 4%. O teto distinto existe para que a lentidão de um integrador não se torne a lentidão de todos.

04O que é contado, e para quem #sec_f6c8dcbb

O contador está ligado ao cliente autenticado, não ao endereço IP. Dois processos que partilham um client_id partilham o seu teto, onde quer que funcionem; dois clientes distintos na mesma máquina têm cada um o seu.

O ponto de pedido de tokens é uma exceção antes da autenticação: não tendo ainda um cliente, conta por endereço IP.

Consequência prática: se várias integrações tiverem de viver lado a lado, dê a cada uma o seu próprio cliente em vez de partilhar um segredo. Elas deixarão de se incomodar, e um excesso designará a culpada.

05A recusa #sec_7af04e67

Um excesso devolve 429 Too Many Requests, com um cabeçalho Retry-After e um corpo application/problem+json.

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "type": "https://docs.reviewit.example/problems/rate-limit",
  "title": "Too many requests",
  "status": 429,
  "detail": "The rate limit for this client has been exceeded. Retry after the indicated delay.",
  "instance": "/api/v1/evidence/4821"
}

instance traz o caminho recusado: numa integração que chama vários domínios, é este campo que diz qual excedeu.

06Tentar novamente #sec_41e4809f

O teto é uma janela fixa de um minuto, não um débito suavizado. O contador volta a zero no início de cada minuto, não se recarrega progressivamente.

Espere o atraso indicado por Retry-After. Tentar novamente antes só consome a janela seguinte, e um cliente que se repete sem esperar fica bloqueado indefinidamente, ao mesmo tempo que faz crer que houve uma falha.

Não há fila de espera. Um pedido além do teto é recusado imediatamente, não é colocado em espera. É deliberado: uma resposta rápida que diz não é mais útil do que uma resposta lenta que acaba por dizer sim, porque deixa ao cliente a escolha de abrandar.

07Manter-se abaixo do limite #sec_767baf63

Três gestos, pela ordem em que são relatados.

O primeiro: guardar o token. Um token vive uma hora; pedir um novo a cada chamada esgota o limite de tokens — o mais baixo dos três — bem antes do limite de dados.

O segundo: aumentar o tamanho da página em vez de multiplicar as chamadas. Quinhentos elementos em uma solicitação custam um token de débito; os mesmos quinhentos em cinco solicitações custam cinco.

O terceiro: espaçar as provas. Elas têm seu próprio limite e também consomem o padrão; agrupá-las em rajada é a maneira mais rápida de atingir os dois.

08A lembrar #sec_2dde19f8

Seiscentos chamados por minuto, sessenta para as provas que se somam ao padrão, sessenta para os tokens. Um contador por cliente autenticado. Uma recusa imediata, nunca uma fila de espera. E Retry-After que diz exatamente quanto tempo esperar.