Rate limits
Escreva o cliente contra os cabeçalhos, e não contra um número
As quotas variam por plano e mudam ao longo do tempo. A forma da política não: leia os cabeçalhos, recue com variação aleatória, e use a via em massa para trabalho em massa.
- Aplicado por
- Organização
- Sinalizado por
- Cabeçalhos de resposta
- Resolução
- Contabilizado à parte
Definition
Como são aplicados os limites de taxa da API?
Os limites aplicam-se por organização e por classe de endpoint, e são comunicados em cada resposta através de cabeçalhos que indicam o limite, a quota restante e a hora de reposição. A resolução pública do passaporte é contabilizada à parte da sua quota, porque uma rajada de leituras não pode consumir o orçamento de um pipeline de emissão.
A client written against the headers keeps working when a quota changes. A client written against a number from a documentation page does not, and fails at the least convenient moment.
Classes
Nem todos os endpoints são contabilizados da mesma forma
| Class | Example | How it is governed |
|---|---|---|
| Public resolution | A consumer scanning a data carrier | Caching and edge capacity, not your quota |
| Read | Fetching a passport or an object history | Account quota, generous, cache-friendly |
| Write | Issuing a passport, appending an event | Account quota, lower ceiling than read |
| Bulk | Back catalogue import, historic event backfill | Asynchronous job with its own concurrency limit |
| Credential operations | Issuing or verifying a signed claim | Metered separately; cryptographic work is not free |
Cabeçalhos
O que cada resposta lhe diz
RateLimit-Limit: the ceiling for this endpoint class
RateLimit-Remaining: what is left in the current window
RateLimit-Reset: seconds until the window resets
Retry-After: present on 429 — honour this first
# Back off with jitter. A fixed interval across many workers
# turns one brief limit into a sustained one.
const delay = Math.min(2 ** attempt * base, ceiling);
await sleep(delay * (0.5 + Math.random() / 2));Conceção do cliente
O que faz um cliente bem comportado
Lê os cabeçalhos
Adapta-se à quota em vigor em vez de assumir um valor documentado.
Recua com variação aleatória
Atraso aleatório, para que workers paralelos não repitam em uníssono.
Usa a via em massa
O carregamento de histórico passa pelo modo em massa, não por um ciclo sobre um endpoint de recurso único.
Separa os pipelines
Emissão e reporte em chaves distintas, para que uma não possa esfomear a outra.
Limita as suas repetições
Desiste e expõe a falha em vez de repetir indefinidamente.
Avisa antes do limite
Alertas sobre a quota restante, para que o primeiro sinal não seja um 429 em produção.
Respostas
Perguntas frequentes
Quais são os limites reais?
Dependem do seu plano e da classe do ponto de extremidade, e constam do seu contrato e não daqui. Um número publicado ficaria desatualizado no espaço de uma versão, e quem dimensionasse por ele descobriria o limite real em produção. Leia antes os cabeçalhos — esses estão sempre atualizados.
Como deve um cliente reagir a um 429?
Respeite `Retry-After` se estiver presente; caso contrário, recue exponencialmente com variação aleatória e limite o número de tentativas. Repetir de imediato, ou a intervalo fixo a partir de muitos workers, transforma um limite breve num limite prolongado — a debandada que faz de um pequeno problema uma indisponibilidade.
A resolução pública do passaporte é limitada da mesma forma?
Não. A resolução é pública, cacheável e naturalmente sujeita a rajadas, pelo que é governada por cache e capacidade de edge, e não pela sua quota. Um produto que se torna viral não deve consumir a quota de que o seu pipeline de emissão depende, e é por isso que os dois caminhos são contabilizados em separado.
Como carregamos um grande catálogo histórico?
Pelo caminho de importação em massa e não iterando o ponto de extremidade de recurso único. O modo em massa foi concebido para o débito e corre de forma assíncrona com uma tarefa que se consulta; o ponto de extremidade por recurso foi concebido para a latência. Usar o errado é a causa mais comum de limitação de taxa autoinfligida.
Os limites aplicam-se por chave ou por organização?
Por organização, com visibilidade por chave. Isso conta quando delimita chaves por serviço: um serviço com mau comportamento pode consumir o orçamento partilhado, e a repartição por chave é o que lhe permite encontrá-lo depressa em vez de por eliminação.
Next step
Diga-nos os seus volumes antes de construir
Dimensão do catálogo, ritmo de emissão e pico sazonal. Preferimos dimensionar bem o plano a que descubra um teto em produção.