Limites de taxa e códigos de erro da API

Baldes

Cada rota tem um balde, contado separadamente por recurso principal (canal, servidor, webhook ou interação) e por quem chama. Toda resposta da v1 traz:

X-RateLimit-Limit: pedidos permitidos na janela.
X-RateLimit-Remaining: quantos ainda restam.
X-RateLimit-Reset: quando zera (epoch em segundos, com decimais).
X-RateLimit-Reset-After: segundos até zerar.
X-RateLimit-Bucket: identificador do balde (rotas diferentes podem dividir o mesmo).

429

HTTP/1.1 429 Too Many Requests
Retry-After: 2
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1793700123.512
X-RateLimit-Reset-After: 1.512
X-RateLimit-Bucket: 9f2c1a7b3e4d5c6f
X-RateLimit-Scope: shared

{ "code": "RATE_LIMITED", "message": "You are being rate limited", "status": 429, "retryAfter": 1.512, "retry_after": 1.512, "global": false }

Espere retryAfter segundos (ou o cabeçalho Retry-After) antes de tentar de novo. X-RateLimit-Scope diz se o limite é seu (user), global (global) ou do recurso (shared). Há também um limite global de 50 pedidos por segundo por bot (as respostas de interação ficam de fora). Endereços que acumulam muitos 401/403 ficam bloqueados por 10 minutos.

Erros

UNAUTHORIZED (401): token ausente, inválido ou trocado.
MISSING_SCOPE / BOT_ONLY (403): o token OAuth2 não tem o escopo, ou a rota é só para bots.
MISSING_PERMISSIONS (403): falta permissão no servidor ou no canal.
MISSING_INTENT (403): ative a intent privilegiada no portal.
NOT_FOUND (404): não existe ou o bot não enxerga.
VALIDATION (400): corpo ou parâmetros inválidos (detail explica).
INTERACTION_ALREADY_ACKNOWLEDGED (400): a interação já foi respondida ou passou dos 3 segundos.
RATE_LIMITED (429) e INTERNAL (500).

Limites de taxa e erros

Baldes

429

Erros