Erro ‘Invalid Form Body’ no Webhook do Discord: Como Corrigir

Ao tentar enviar uma mensagem usando um webhook do Discord, você pode ver o erro Invalid Form Body. Esse erro significa que o payload JSON enviado para a URL do webhook contém dados que o Discord não consegue processar. A causa geralmente é um campo obrigatório ausente, um tipo de dado incorreto ou um caractere que viola as regras de conteúdo do Discord. Este artigo explica os motivos mais comuns para esse erro e fornece correções passo a passo para cada caso.

Por que os Webhooks do Discord Retornam Invalid Form Body

Os webhooks do Discord aceitam requisições HTTP POST com um corpo JSON. O servidor valida o payload contra regras estritas. Se alguma regra for violada, o Discord retorna o erro Invalid Form Body junto com o nome do campo específico e o motivo. A causa raiz é quase sempre uma das seguintes:

Campos Obrigatórios Ausentes

O payload mais simples deve conter pelo menos o campo content ou um array embeds com pelo menos um objeto embed. Se você enviar um corpo JSON vazio {} ou omitir ambos os campos, o Discord rejeita.

Tipos de Dados Incorretos

O Discord espera tipos de dados específicos para cada campo. Por exemplo, content deve ser uma string, embeds deve ser um array, e color dentro de um embed deve ser um inteiro. Enviar um número onde se espera uma string, ou vice-versa, dispara o erro.

Violações de Caractere ou Tamanho

O Discord impõe limites de caracteres em quase todos os campos de texto. O campo content é limitado a 2000 caracteres. Títulos de embed podem ter até 256 caracteres, descrições até 4096, e texto de rodapé até 2048. Exceder esses limites causa o erro.

Passos para Corrigir o Erro Invalid Form Body

A correção depende da mensagem de erro exata. Abaixo estão os padrões de erro mais comuns e suas soluções.

Correção 1: Adicione o Campo Content

1. Verifique se seu payload tem o campo content
   Se seu corpo JSON for {} ou contiver apenas um array embeds, o Discord exige pelo menos um desses campos. Adicione "content": "Sua mensagem aqui" à raiz do objeto JSON.
2. Verifique se o campo content é uma string
   Certifique-se de que o valor de content está entre aspas duplas. Enviar "content": 123 falhará porque 123 é um inteiro, não uma string.

Correção 2: Corrija a Estrutura do Objeto Embed

1. Garanta que cada embed tenha pelo menos um campo obrigatório
   Cada objeto embed deve conter um campo title, description ou url. Um objeto embed vazio {} produzirá o erro. Adicione pelo menos um desses campos.
2. Verifique a contagem de campos do embed
   Um embed pode ter até 25 campos no array fields. Se você tiver 26 ou mais campos, reduza o número para 25 ou menos.
3. Valide o valor da cor
   O campo color deve ser um inteiro representando um código de cor decimal. Por exemplo, "color": 16711680 para vermelho. Não use strings hex como "#FF0000".

Correção 3: Ajuste o Texto para os Limites de Tamanho

1. Conte os caracteres em content
   Use uma ferramenta de contagem de caracteres para verificar se o campo content tem 2000 caracteres ou menos. Se exceder o limite, encurte a mensagem.
2. Verifique o tamanho da descrição do embed
   O campo description dentro de um embed é limitado a 4096 caracteres. Se sua descrição for mais longa, divida-a em vários embeds ou trunque o texto.
3. Ajuste o título e o texto do rodapé do embed
   Títulos de embed não podem exceder 256 caracteres. O texto do rodapé não pode exceder 2048 caracteres. Reduza esses valores se necessário.

Correção 4: Remova Caracteres Não Suportados

1. Escape caracteres especiais no JSON
   Aspas duplas dentro de uma string devem ser escapadas com uma barra invertida: \". Novas linhas podem ser representadas como \n. Barras invertidas devem ser duplicadas: \\. Verifique se há caracteres não escapados no seu payload.
2. Evite Unicode não suportado
   O Discord suporta a maioria dos caracteres Unicode, mas alguns caracteres de controle (U+0000 a U+001F) não são permitidos. Remova ou substitua-os.

Se o Erro Persistir Após a Correção Principal

Mesmo após corrigir o payload, você ainda pode receber o erro. Aqui estão verificações adicionais a serem feitas.

URL do Webhook Está Incorreta ou Expirada

Verifique se a URL do webhook está completa e inclui o ID e token corretos. Um erro de digitação na URL causará um erro 404 ou 400, que pode parecer semelhante. Copie a URL do webhook diretamente de Configurações do Servidor Discord > Integrações > Webhooks.

Payload Contém Campos Extras

O Discord ignora campos desconhecidos, mas pode rejeitar o payload se um campo tiver um tipo inesperado. Por exemplo, adicionar "tts": "yes" em vez de "tts": true falhará porque tts deve ser booleano. Remova quaisquer campos dos quais você não tem certeza.

Limitação de Taxa Não é o Problema

Se você enviar muitas requisições rapidamente, o Discord pode retornar um erro 429 Too Many Requests, não Invalid Form Body. A mensagem de erro dirá claramente 429. Se você vir 400 com Invalid Form Body, o problema é o payload, não o limite de taxa.

Campos do Payload do Webhook do Discord: Obrigatórios vs Opcionais

Campo	Obrigatório	Tamanho Máximo / Tipo
content	Sim, se não houver embeds	String, 2000 caracteres
embeds	Sim, se não houver content	Array de objetos embed, máximo 10 embeds
embeds[].title	Não, mas pelo menos um dos campos title, description ou url é obrigatório por embed	String, 256 caracteres
embeds[].description	Não	String, 4096 caracteres
embeds[].color	Não	Inteiro (código de cor decimal)
embeds[].fields	Não	Array, máximo 25 objetos de campo

Após corrigir o payload, teste o webhook enviando uma mensagem simples primeiro. Use uma ferramenta como Postman ou curl para enviar uma requisição POST para a URL do webhook com um corpo JSON mínimo: {"content": "Mensagem de teste"}. Assim que isso funcionar, adicione gradualmente mais campos. Se o erro reaparecer, verifique o campo que você acabou de adicionar. Essa abordagem incremental isola o problema rapidamente.