Operações que escrevem (POST, PUT, PATCH, DELETE) têm teto de 60 requisições por
minuto, em janela fixa. Leituras não são limitadas.
As credenciais — do classroom e do dashboard — têm um teto próprio, por cima desse: os POST
de /v1/auth/* (cadastro, entrada, confirmação, redefinição e troca de código, tanto do aluno
quanto de quem administra em /v1/auth/admin/*) aceitam 10 por minuto por IP. É o teto de quem chuta senha, e por isso é estrito — ver abaixo. Ler a sessão
(GET /v1/auth/session) e encerrá-la (DELETE) não entram nele: a primeira é leitura, e a
segunda já exige a sessão que se está tentando adivinhar.
A caixa de entrada dos webhooks (POST /webhooks/{platform}/{token}) tem teto próprio,
de 600 por minuto por IP: um lançamento com centenas de vendas chega inteiro do mesmo IP
da plataforma, e o teto de escrita o barraria. Ao estourar, a plataforma recebe 429 e reenvia
— nenhum evento é perdido, só adiado.
As escritas do classroom (/v1/clubs/{clubId}/classroom/…, o progresso do aluno) têm teto de
600 por minuto por aluno: é escrita frequente por natureza — o player grava a posição a
cada poucos segundos — e o sujeito ali é o aluno, não o club, senão todos os alunos online
dividiriam um balde só.
O teto é por club nas demais rotas escopadas (/v1/clubs/{clubId}/…) e por IP fora
delas.
A diferença importa nos dois sentidos: um club inteiro atrás de uma mesma saída de rede não
divide cota com os outros, e distribuir as chamadas por vários IPs não multiplica o teto de
um club.
Ao estourar, a resposta é 429 com o código rate_limited e o cabeçalho Retry-After em
segundos:
Quando o contador falha
Se o contador ficar indisponível, escritas comuns passam em vez de serem recusadas —
disponibilidade vence rigor num endpoint que não move dinheiro. Já as credenciais do classroom
respondem 503 com rate_limit_unavailable: nelas, rodar sem freio é pior que uma
indisponibilidade curta da tela de entrada.
Respeite o Retry-After em vez de tentar de novo imediatamente. A janela é fixa: repetir
antes do prazo só consome o teto da janela seguinte.