O Telm mede a API de duas formas: um limite de taxa por minuto (um teto de rajada) e uma cota diária (o seu orçamento total para o dia UTC). Ambos escalam com o plano. Toda resposta medida retorna X-Quota-Limit, X-Quota-Used e X-Quota-Reset para que você sempre saiba o seu orçamento restante, e ambos os limites retornam 429 com um cabeçalho Retry-After quando excedidos.
1Dois limites: taxa por minuto e cota diária
Há dois tetos separados. O limite de taxa por minuto limita quantas requisições você pode fazer dentro de qualquer minuto, suavizando rajadas. A cota diária é o seu orçamento geral: limita quantas chamadas medidas você pode fazer ao longo de todo o dia UTC.
Eles são independentes. Você pode atingir o limite por minuto ainda tendo bastante cota diária restante (você está simplesmente enviando rápido demais), ou esgotar a sua cota diária estando bem abaixo do limite por minuto (você usou o dia). Ambos retornam um status 429, mas por motivos diferentes — verifique o código de erro no corpo para distingui-los.
- Limite de taxa por minuto — um teto de rajada, zera a cada minuto.
- Cota diária — o total de chamadas medidas do dia, zera à meia-noite UTC.
- A cota é contada uma vez por conta, compartilhada por todas as suas chaves.
2Cota diária por plano
A sua cota diária é o número de chamadas de API medidas que você pode fazer por dia UTC, e depende do seu plano. O contador é compartilhado por todas as suas chaves e segue o melhor plano entre os grupos que você administra — sem uma assinatura paga, você está no nível Free.
A janela é o dia calendário UTC, então o seu contador de uso zera à meia-noite UTC. Uma verificação de spam em lote custa uma chamada por item no lote, não uma chamada para a requisição inteira.
- Free — 100 chamadas por dia.
- Basic — 1.000 chamadas por dia.
- Pro — 10.000 chamadas por dia.
- Business — 50.000 chamadas por dia.
3Limite de taxa por minuto por plano
Além da cota diária, cada chave de API é limitada a um número de requisições por minuto de acordo com o nível do seu plano. Este é um limite de suavização: impede que um único cliente envie um pico enorme em um segundo, mesmo quando o orçamento diário está longe de esgotado.
Separadamente, tetos amplos por IP e por conta se aplicam a toda a API para manter a plataforma estável. Em uso normal — requisições constantes e ritmadas — você nunca chegará a tocá-los; eles só disparam em rajadas abusivas.
- Free e Basic — 60 requisições por minuto.
- Pro — 600 requisições por minuto.
- Business — 1.800 requisições por minuto.
- Distribua as requisições em vez de disparar todas de uma vez.
4Lendo o seu orçamento restante
Você nunca precisa adivinhar quanta cota resta. Toda resposta medida — sucesso ou falha — inclui três cabeçalhos: X-Quota-Limit (o seu limite diário), X-Quota-Used (quantas chamadas você gastou hoje) e X-Quota-Reset (o momento, em UTC, em que o contador zera).
Os endpoints de verificação de spam também ecoam os mesmos números dentro do corpo da resposta sob um objeto quota, para que você possa ler o seu orçamento restante sem analisar cabeçalhos. Use-os para ritmar as suas próprias requisições e para se avisar antes de esgotá-lo.
- X-Quota-Limit — o seu limite diário de chamadas.
- X-Quota-Used — chamadas gastas até agora hoje.
- X-Quota-Reset — horário de reset em UTC (RFC 3339).
- As respostas de verificação de spam também incluem um objeto quota com os mesmos campos.
5O que acontece no 429
Quando você cruza qualquer um dos limites, a API retorna HTTP 429 com um cabeçalho Retry-After dizendo quantos segundos esperar. Para o limite de taxa por minuto, o Retry-After é cerca de um minuto. Para a cota diária, o corpo carrega um código daily_quota_exceeded mais o seu plano, limite, contagem de uso, o horário de reset e uma dica de upgrade, e o Retry-After faz a contagem regressiva até a meia-noite UTC.
A forma certa de lidar com um 429 é recuar e retentar após o atraso do Retry-After, não martelar o endpoint. Clientes bem-comportados leem o cabeçalho e pausam; clientes que continuam retentando imediatamente só permanecem bloqueados.
- 429 rate_limit_exceeded — você enviou rápido demais; espere cerca de um minuto.
- 429 daily_quota_exceeded — o dia acabou; espere até o reset UTC ou faça upgrade.
- Sempre respeite o cabeçalho Retry-After antes de retentar.