Error ‘invalid form body’ en webhook de Discord: solución

Cuando intentas enviar un mensaje usando un webhook de Discord, puedes ver el error Invalid Form Body. Este error significa que el payload JSON que enviaste a la URL del webhook contiene datos que Discord no puede procesar. La causa suele ser un campo obligatorio faltante, un tipo de datos incorrecto o un carácter que infringe las reglas de contenido de Discord. Este artículo explica las razones más comunes de este error y proporciona soluciones paso a paso para cada caso.

Por qué los webhooks de Discord devuelven Invalid Form Body

Los webhooks de Discord aceptan solicitudes HTTP POST con un cuerpo JSON. El servidor valida el payload según reglas estrictas. Si se infringe alguna regla, Discord devuelve el error Invalid Form Body junto con un nombre de campo específico y el motivo. La causa raíz casi siempre es una de las siguientes:

Campos obligatorios faltantes

El payload más simple debe contener al menos el campo content o un array embeds con al menos un objeto embed. Si envías un cuerpo JSON vacío {} u omites ambos campos, Discord lo rechaza.

Tipos de datos incorrectos

Discord espera tipos de datos específicos para cada campo. Por ejemplo, content debe ser una cadena, embeds debe ser un array y color dentro de un embed debe ser un entero. Enviar un número donde se espera una cadena, o viceversa, provoca el error.

Infracciones de caracteres o longitud

Discord aplica límites de caracteres en casi todos los campos de texto. El campo content está limitado a 2000 caracteres. Los títulos de embed pueden tener hasta 256 caracteres, las descripciones hasta 4096 y el texto del pie de página hasta 2048. Superar estos límites provoca el error.

Pasos para solucionar el error Invalid Form Body

La solución depende del mensaje de error exacto. A continuación se muestran los patrones de error más comunes y sus soluciones.

Solución 1: Agregar el campo Content

1. Verifica tu payload para el campo content
   Si tu cuerpo JSON es {} o contiene solo un array embeds, Discord requiere al menos uno de estos campos. Agrega "content": "Your message here" en la raíz del objeto JSON.
2. Verifica que el campo content sea una cadena
   Asegúrate de que el valor de content esté entre comillas dobles. Enviar "content": 123 fallará porque 123 es un entero, no una cadena.

Solución 2: Corregir la estructura del objeto embed

1. Asegúrate de que cada embed tenga al menos un campo requerido
   Cada objeto embed debe contener un campo title, description o url. Un objeto embed vacío {} producirá el error. Agrega al menos uno de estos campos.
2. Verifica el recuento de campos del embed
   Un embed puede tener hasta 25 campos en el array fields. Si tienes 26 o más campos, reduce el número a 25 o menos.
3. Valida el valor de color
   El campo color debe ser un entero que represente un código de color decimal. Por ejemplo, "color": 16711680 para rojo. No uses cadenas hexadecimales como "#FF0000".

Solución 3: Recortar el texto para ajustarse a los límites de longitud

1. Cuenta los caracteres en content
   Usa una herramienta de conteo de caracteres para verificar que el campo content tenga 2000 caracteres o menos. Si supera el límite, acorta el mensaje.
2. Verifica la longitud de la descripción del embed
   El campo description dentro de un embed está limitado a 4096 caracteres. Si tu descripción es más larga, divídela en varios embeds o trunca el texto.
3. Recorta el título y el texto del pie de página del embed
   Los títulos de embed no pueden superar los 256 caracteres. El texto del pie de página no puede superar los 2048 caracteres. Reduce estos valores si es necesario.

Solución 4: Eliminar caracteres no admitidos

1. Escapa caracteres especiales en JSON
   Las comillas dobles dentro de una cadena deben escaparse con una barra invertida: \". Los saltos de línea se pueden representar como \n. Las barras invertidas deben duplicarse: \\. Verifica tu payload en busca de caracteres sin escapar.
2. Evita Unicode no admitido
   Discord admite la mayoría de los caracteres Unicode, pero algunos caracteres de control (U+0000 a U+001F) no están permitidos. Elimínalos o reemplázalos.

Si el error persiste después de la solución principal

Incluso después de corregir el payload, es posible que sigas recibiendo el error. Aquí hay verificaciones adicionales que puedes realizar.

La URL del webhook es incorrecta o ha caducado

Verifica que la URL del webhook esté completa e incluya el ID y el token correctos. Un error tipográfico en la URL provocará un error 404 o 400, que puede parecer similar. Copia la URL del webhook directamente desde Discord Server Settings > Integrations > Webhooks.

El payload contiene campos adicionales

Discord ignora los campos desconocidos, pero puede rechazar el payload si un campo tiene un tipo inesperado. Por ejemplo, agregar "tts": "yes" en lugar de "tts": true fallará porque tts debe ser un booleano. Elimina cualquier campo del que no estés seguro.

La limitación de velocidad no es el problema

Si envías muchas solicitudes rápidamente, Discord puede devolver un error 429 Too Many Requests, no Invalid Form Body. El mensaje de error dirá claramente 429. Si ves 400 con Invalid Form Body, el problema es el payload, no el límite de velocidad.

Campos del payload del webhook de Discord: obligatorios vs opcionales

Campo	Obligatorio	Longitud máxima / Tipo
content	Sí, si no hay embeds presentes	Cadena, 2000 caracteres
embeds	Sí, si no hay content presente	Array de objetos embed, máximo 10 embeds
embeds[].title	No, pero se requiere al menos uno de title, description o url por embed	Cadena, 256 caracteres
embeds[].description	No	Cadena, 4096 caracteres
embeds[].color	No	Entero (código de color decimal)
embeds[].fields	No	Array, máximo 25 objetos de campo

Después de corregir el payload, prueba el webhook enviando primero un mensaje simple. Usa una herramienta como Postman o curl para enviar una solicitud POST a la URL del webhook con un cuerpo JSON mínimo: {"content": "Test message"}. Una vez que eso funcione, agrega más campos gradualmente. Si el error reaparece, verifica el campo que acabas de agregar. Este enfoque incremental aísla el problema rápidamente.