Erros e limites

Formato de erro, status HTTP e limites de requisição.

Formato de erro

Toda falha responde com um status HTTP e um JSON com a mensagem em português. Não há códigos numéricos de erro — use o status HTTP para decidir o que fazer.

Exemplo

{ "error": "Você não tem permissão para fazer isso nesse canal" }

Algumas respostas trazem uma marcação extra:

Campo	Quando
`automod: true`	A auto-moderação do servidor bloqueou a mensagem (`422`).
`requiresRulesAcceptance: true`	O servidor exige aceitar as regras (rota humana de mensagens).
`verificationLevelBlocked: true`	O nível de verificação do servidor bloqueou o envio (rota humana).
`requires2FA: true`	Ação de moderação num servidor que exige 2FA — bots não passam.

Status HTTP

Status	Significado
400	Corpo ou parâmetro inválido. A mensagem aponta o campo (ex.: "embeds[0].title: máximo 256 caracteres.").
401	Token ausente, inválido, revogado ou de aplicação suspensa.
403	Sem permissão, rota não permitida para bots/humanos ou intent desligado.
404	Recurso não encontrado (ou não pertence à sua aplicação).
409	Conflito: interação já respondida/expirada, bot já existe, componente não existe mais.
413	Corpo maior que o limite (ícone acima de 2 MB, JSON acima de 20 MB).
422	Mensagem bloqueada pela auto-moderação.
429	Limite de requisições excedido.
500	Erro interno. Tente de novo com espera.

Limites de requisição

Os limites contam por conta (o bot) e por tipo de ação, numa janela deslizante.

Atenção

A resposta 429 não traz Retry-After nem cabeçalhos X-RateLimit-*. Espere a janela da tabela e tente de novo, de preferência com backoff.

Ação	Limite
`POST /api/bot/…/messages`	10 a cada 10 s
`PATCH /api/bot/…/messages/:id`	10 a cada 10 s
`POST /api/servers/…/messages`	10 a cada 10 s
`PUT /api/bot/commands`	20 por minuto
`PUT /api/bot/presence`	30 por minuto
Criar aplicação / gerar bot	10 por hora cada
Rotacionar token / segredos	20 por hora cada
Concluir instalação	30 por hora
Testar URL de interações	10 por minuto
`POST /api/bot/interactions/:id/respond`, `GET /api/bot/*`	sem limite específico

Outras regras gerais

Base: https://nexapp.online/api. Corpo sempre JSON, até 20 MB.
IDs são UUIDs (strings).
Datas vêm como texto UTC ("2026-10-05 14:30:00") ou ISO 8601.
Respostas da API não são cacheadas (Cache-Control: no-store).