Erros e limites
Limites de taxa, códigos de erro da API, boas práticas e a tabela-resumo de limites da plataforma.
Limites de taxa#
Ao estourar, a API responde 429.
| Limite | Valor |
|---|---|
| Envio de mensagens por canal (inclui respostas de interação não efêmeras) | 5 a cada 5 segundos por bot e canal |
| Requisições às rotas de servidor | 50 por segundo por bot |
| Rotas de envio de mensagens, reações | 60 por minuto cada |
| Demais rotas | 300 por minuto, ou o limite próprio da rota (comandos em massa: 20 por minuto) |
Nos limites de bot, o corpo é { "error": "...", "retryAfterMs": 4182 } e vem o cabeçalho Retry-After (segundos). Espere retryAfterMs antes de tentar de novo. O projeto bot/ faz isso sozinho (até 5 tentativas).
# exemplo de 429
# HTTP/1.1 429 Retry-After: 5
# {"error":"Você está sendo limitado. Tente novamente em instantes.","retryAfterMs":4182}Erros comuns da API#
| Código | Quando |
|---|---|
| 400 | Corpo inválido (mensagem vazia, embed inválido, comando mal formado, Anexo inválido.) |
| 401 | Token ausente ou inválido (Token de bot inválido.) |
| 403 | Falta permissão (inclui O bot não pode anexar arquivos aqui.), rota proibida a bots, ou bot privado |
| 413 | Arquivo acima de 100 MB em POST /attachments/init |
| 404 | Servidor, canal ou mensagem inexistente, ou o bot não está no servidor |
| 409 | Conflito (limite de comandos, interação já respondida) |
| 410 | Interação expirada |
| 429 | Limite de taxa |
Boas práticas e limites#
- Guarde o token em variáveis de ambiente. Nunca no Git. Redefina se vazar.
- Ignore as próprias mensagens (
author.bot) para não entrar em loop, e de preferência ignore todos os bots. - Peça só as permissões necessárias. O usuário vê a lista antes de confirmar.
- Registre comandos com PUT na inicialização (idempotente) em vez de criar um por um.
- Responda interações em menos de 3 segundos. Se a tarefa for demorar, use
defer. - Respeite os 429. Espere
retryAfterMs, não insista em laço apertado. - Mensagens grandes: quebre em partes de até 2000 caracteres, ou use embed (descrição de 4096).
- Reconecte com backoff e trate 4001/4003 como erros fatais.
- Rode uma instância por bot. O limite é de 2 conexões; a segunda serve para trocar de versão sem ficar offline, mas as duas recebem os mesmos eventos de mensagem (cada interação, ao contrário, é entregue a uma conexão só). Evite responder em duplicidade.
- Busque ids no gateway (
GUILD_CREATE) em vez de chamarGET /guilds/:gem cada evento.
Resumo dos limites:
| Item | Limite |
|---|---|
| Aplicativos por pessoa | 10 |
| Nome do aplicativo | 2 a 32 caracteres |
| Descrição / tags | 400 caracteres / 5 tags de até 20 caracteres |
| Nome de usuário do bot | 3 a 20 letras minúsculas, números ou _ |
| Comandos por escopo | 100 |
| Opções por comando | 25 |
| Mensagem | 2000 caracteres |
| Embeds por mensagem | 10 (6000 caracteres no total) |
| Anexos | 100 MB por arquivo; 4 a 10 por mensagem (nível de Pulse do servidor); 10 envios pendentes por bot; 20 init por minuto |
| Conexões de gateway por bot | 2 |
| Mensagens ao gateway | 120 por minuto, 64 KiB cada |
| Envio por canal | 5 a cada 5 segundos |
| Interação | 3 s para responder, 15 min de validade, 5 follow-ups |
Para diagnosticar problemas, veja também as Perguntas frequentes.