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ó.
Publicar comentário (POST …/classroom/lessons/{publicId}/comments e
POST …/classroom/posts/{publicId}/comments, comentário ou resposta) tem teto próprio e pequeno,
de 10 por minuto por aluno: é a escrita que os colegas leem, e o teto largo do classroom
deixaria espalhar spam à vontade. Reagir e editar continuam no teto do classroom.
Publicar post na comunidade (POST …/classroom/community/spaces/{spaceId}/posts) tem o teto
mais longo de todos, de 20 por hora por aluno: um post abre uma conversa para a comunidade
inteira, e spam em comunidade vem de conta legítima — um teto por minuto deixaria uma pessoa
publicar centenas por dia. Quem administra publica pelo teto de escrita do club.
Reservar e desmarcar sessão de mentoria (POST …/classroom/mentorships/{publicId}/bookings e
DELETE …/classroom/mentorships/{publicId}/sessions/{sessionId}) dividem um teto de 30 por hora
por aluno: cada um vira um e-mail para quem mentora, e o teto do classroom deixaria um laço de
reserva e cancelamento encher a caixa de alguém. Escrever a pauta e avaliar ficam no teto do
classroom.
Perguntar a um agente (POST …/classroom/agents/{publicId}/messages) tem teto de 20 por
minuto por aluno: é o freio de quem dispara um laço. O teto que de fato limita a conversa é de
produto e responde com códigos próprios — as perguntas por aluno em 24 horas que cada agente
define (429 daily_limit_reached) e o orçamento de IA do club no mês
(429 club_budget_exhausted). Ver Agentes.
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.