Limites de requisição

As requisições são medidas por token buckets distribuídos. Vários se aplicam ao mesmo tempo, e o mais restrito vence.

Bucket	Aplica-se a	Cota
client	Toda requisição do plano de dados, por credencial	120/min, ajustável por credencial
company	Toda requisição do plano de dados, somando as credenciais da empresa	600/min
transcript	Só leitura de transcrição, além dos dois acima	60/min
oauth-client	POST /oauth/token, por client id	10/min, burst 5
oauth-ip	POST /oauth/token, por IP de origem, e GET /oauth/authorize	30/min, burst 10
oauth-grant	POST /oauth/token com grant_type=authorization_code ou refresh_token, por conexão	10/min, burst 5
oauth-revoke	POST /oauth/revoke, por conexão	10/min, burst 5

Uma empresa pode ter até 20 credenciais de empresa ativas; credenciais de usuário não entram nesse limite, e todas as credenciais da empresa usam a mesma cota da empresa. Use GET /v1/context para ler a cota de credencial em vigor para a sua.

O bucket oauth-grant é de uma conexão feita entrando com OAuth, então quem está atrás do mesmo endereço nunca o divide, e esse grant não é cobrado do oauth-ip. Um grant que não corresponde a nenhuma conexão, por exemplo um code desconhecido, é cobrado do oauth-ip. Os documentos de metadados em /.well-known/ não têm rate limit.

O POST /oauth/revoke é cobrado do mesmo jeito. Um token ainda válido de uma conexão, seja o refresh token dela ou um dos access tokens, é cobrado do bucket oauth-revoke daquela conexão; qualquer outro token é cobrado do oauth-ip.

Headers

Toda resposta traz o estado atual. O RateLimit-Policy lista todos os buckets que a requisição consumiu; o RateLimit informa apenas o que está mais perto de esgotar:

RateLimit-Policy: "client";q=120;w=60, "company";q=600;w=60
RateLimit: "client";r=118;t=1

q é a cota, w a janela em segundos, r o que resta e t os segundos até o próximo token. O RateLimit nomeia o bucket com menos tokens no momento: normalmente o da sua credencial, o de transcrição nas leituras de transcrição, e o da empresa quando as outras credenciais estão gastando. Ritme suas chamadas pelos tetos do RateLimit-Policy — o bucket de uma leitura não é o único que te limita.

O r conta tokens no bucket, cuja capacidade é o burst e não a cota, então ele não começa em q e decrementa. Leia como espaço disponível agora.

Uma requisição recusada devolve 429 RATE_LIMIT_EXCEEDED com Retry-After em segundos. Espere esse tempo — não repita na hora, e adicione jitter para que uma frota de workers não volte a sincronizar na janela seguinte.

Comportamento quando o limitador degrada

Os caminhos de leitura falham abertos: se o limitador ficar brevemente inacessível, as leituras de negócio continuam servindo em vez de cair.

Emissão de token, leitura de transcrição e rotas internas de control plane falham fechadas com 503 SERVICE_UNAVAILABLE. São os caminhos em que servir tráfego sem medição é pior que não servir.

O limite do WAF é separado

Há um limite grosseiro por IP no WAF, antes de o tráfego chegar ao serviço, e ele não faz parte das cotas acima: cerca de 2000 requisições por cinco minutos por IP de origem, e 100 por cinco minutos no /oauth/token. Os grants authorization_code e refresh_token não contam no limite por IP do WAF; o serviço os limita com os buckets oauth-grant e oauth-ip descritos acima. O GET /oauth/authorize e o POST /oauth/revoke continuam sujeitos ao limite geral por IP.

Ele falha de outro jeito, e isso importa quando você o encontra:

• corta com 403, não 429, então parece falha de autorização;
• não vem código de erro, nem Retry-After, nem headers de rate limit, porque a requisição nunca chega ao serviço;
• conta por IP de origem, então toda integração atrás do mesmo endereço de saída divide o mesmo limite, com quais credenciais for.

Um 403 sem nenhum corpo de erro nosso, especialmente no /oauth/token, é esse limite e não falta de escopo.

Como ficar abaixo do limite

• Pagine com limit=100 em vez de muitas páginas pequenas — uma requisição devolve até 100 registros pelo mesmo custo de uma que devolve 10.
• Filtre por período em vez de percorrer todo o histórico repetidamente.
• Guarde o token de acesso; cada chamada a /oauth/token consome bucket próprio.
• Busque transcrição só dos registros que você vai processar. O has_transcript permite filtrar a listagem antes.