O que é limitação de taxa da API?

A limitação de taxa da API restringe as requisições que um cliente pode fazer em um período ou orçamento de recursos definido. Um serviço pode aplicar limites por conta, credencial, endpoint, endereço ou outro escopo de uso.

Um limitador de taxa contabiliza requisições, ou um custo ponderado por requisição, em relação a uma cota que pertence a uma partição, como uma conta, credencial, endereço IP ou endpoint, e mais de uma política pode se aplicar à mesma requisição. O algoritmo de contagem determina como as rajadas são tratadas. Um contador de janela fixa é zerado a cada limite de janela, portanto um cliente pode consumir a cota de uma janela logo antes de o contador ser zerado e a da janela seguinte logo depois. Uma janela deslizante suaviza essa transição, por exemplo, adicionando a contagem da janela anterior ponderada pela proporção dessa janela que ainda se sobrepõe. Um balde de tokens adiciona tokens a uma taxa constante até uma capacidade fixa, e essa capacidade limita a rajada que ele admite. Um balde com vazamento esvazia a uma taxa constante; a implementação do NGINX atrasa as requisições excedentes por padrão e as rejeita quando ultrapassam o tamanho de rajada configurado. Um serviço pode executar vários limitadores em paralelo, por exemplo, uma taxa de requisições, um limite de requisições simultâneas e um orçamento separado para operações caras ou que criam conteúdo, portanto ficar abaixo de um limite não significa ficar abaixo de todos. Quando uma requisição é recusada, a resposta pode informar quanto tempo esperar, o que permite aos clientes distribuir suas novas tentativas em vez de tentar novamente todos ao mesmo tempo.

O HTTP define o status 429 Too Many Requests para uma requisição sujeita à limitação de taxa, e a resposta pode incluir um cabeçalho Retry-After, mas nenhum dos dois é garantido. O GitHub documenta que pode responder com 403 ou 429, junto com um cabeçalho x-ratelimit-remaining de valor 0 ou uma mensagem de erro informando que um limite de taxa foi excedido, e o módulo limit_req do NGINX rejeita com 503, a menos que limit_req_status esteja definido. Detecte a limitação pelos códigos de status, cabeçalhos e corpo de erro documentados pela API, não apenas por 429.
Retry-After é um número de segundos a esperar após o recebimento da resposta ou uma data HTTP, portanto o cliente precisa interpretar ambas as formas. Algumas APIs informam a espera em outro lugar: o GitHub também usa x-ratelimit-reset, um instante em segundos desde a época Unix em UTC, e outros serviços colocam um intervalo de espera no corpo JSON do erro. Leia o tempo de espera no local e na unidade documentados pela API.
Não existe um padrão finalizado para informar a cota restante. Os campos de cabeçalho RateLimit e RateLimit-Policy são um Internet-Draft da IETF (revisão 11, de maio de 2026), não uma RFC, e APIs em uso adotam nomes específicos de cada fornecedor, como x-ratelimit-remaining. O rascunho orienta os clientes a não tratar a cota informada como garantia e dá precedência a Retry-After quando uma resposta contém ambos.
A cota informada pode ser imprecisa, pois limitadores que operam em muitos servidores compartilham ou aproximam seus contadores. O GitHub observa que a contagem restante pode variar de uma resposta para outra quando as requisições são tratadas em várias regiões e desaconselha lógicas que dependam de uma contagem restante exata; o Amazon API Gateway descreve suas limitações e cotas como metas de melhor esforço, não como tetos garantidos. Ajuste o ritmo das requisições com base nos valores informados, mas continue tratando respostas de limitação mesmo quando a última resposta indicava cota disponível.

Os limites de taxa orientam a implementação de qualquer cliente que envie requisições em massa ou em paralelo, como importações, ciclos de consulta periódica, tarefas em lote e lógica de novas tentativas. Identifique os limites documentados pela API e sua resposta de limitação antes de construir o cliente; depois, espere pelo menos o tempo indicado nessa resposta, adicione uma variação aleatória para que as unidades de execução paralelas não tentem novamente todas ao mesmo tempo e limite o número de tentativas. Quando uma resposta de limitação não informar uma espera, use a alternativa documentada pela API ou, na ausência dela, um intervalo que cresça exponencialmente a cada tentativa até um máximo. Tentar novamente de imediato aumenta a carga e pode prolongar a limitação, e alguns provedores, entre eles o GitHub, alertam que uma integração que continue enviando requisições enquanto estiver limitada pode ser banida.

A Transloadit limita a taxa de requisições da própria API e documenta os limites atuais na página de limitação de taxa. Uma requisição rejeitada por exceder um limite de criação ou simultaneidade retorna um erro JSON que informa uma espera recomendada em segundos, e os SDKs oficiais da Transloadit já aplicam esse intervalo de espera e tentam novamente.

A espera informada é um intervalo recomendado entre tentativas: a documentação diz que isso não garante que haverá capacidade disponível após esse período. A mesma página descreve um limite separado de alta frequência, e a resposta apresentada para ele não inclui tempo de espera, portanto um cliente que o trate precisa definir seu próprio intervalo de espera entre tentativas.

Explore os recursos da plataforma da Transloadit

O que é limitação de taxa da API?

Como funciona a limitação de taxa da API

Informações essenciais

Quando a limitação de taxa da API é relevante

Como a Transloadit ajuda com a limitação de taxa da API

Fontes

Transforme conhecimento sobre mídia em um pipeline funcional