Discord Webhook ‘Invalid Form Body’ Error: Fix

When you try to send a message using a Discord webhook, you may see the error Invalid Form Body. This error means the JSON payload you sent to the webhook URL contains data that Discord cannot process. The cause is usually a missing required field, an incorrect data type, or a character that violates Discord’s content rules. This article explains the most common reasons for this error and provides step-by-step fixes for each case.

Why Discord Webhooks Return Invalid Form Body

Discord webhooks accept HTTP POST requests with a JSON body. The server validates the payload against strict rules. If any rule is violated, Discord returns the Invalid Form Body error along with a specific field name and reason. The root cause is almost always one of the following:

Missing Required Fields

The simplest payload must contain at least the content field or an embeds array with at least one embed object. If you send an empty JSON body {} or omit both fields, Discord rejects it.

Incorrect Data Types

Discord expects specific data types for each field. For example, content must be a string, embeds must be an array, and color inside an embed must be an integer. Sending a number where a string is expected, or vice versa, triggers the error.

Character or Length Violations

Discord enforces character limits on almost every text field. The content field is limited to 2000 characters. Embed titles can have up to 256 characters, descriptions up to 4096, and footer text up to 2048. Exceeding these limits causes the error.

Steps to Fix the Invalid Form Body Error

The fix depends on the exact error message. Below are the most common error patterns and their solutions.

Fix 1: Add the Content Field

1. Check your payload for the content field
   If your JSON body is {} or contains only an embeds array, Discord requires at least one of these fields. Add "content": "Your message here" to the root of the JSON object.
2. Verify the content field is a string
   Ensure the value of content is wrapped in double quotes. Sending "content": 123 will fail because 123 is an integer, not a string.

Fix 2: Correct Embed Object Structure

1. Ensure each embed has at least one required field
   Every embed object must contain a title, description, or url field. An empty embed object {} will produce the error. Add at least one of these fields.
2. Check the embed field count
   An embed can have up to 25 fields in the fields array. If you have 26 or more fields, reduce the number to 25 or fewer.
3. Validate the color value
   The color field must be an integer representing a decimal color code. For example, "color": 16711680 for red. Do not use hex strings like "#FF0000".

Fix 3: Trim Text to Fit Length Limits

1. Count the characters in content
   Use a character counter tool to verify that the content field is 2000 characters or fewer. If it exceeds the limit, shorten the message.
2. Check embed description length
   The description field inside an embed is limited to 4096 characters. If your description is longer, split it into multiple embeds or truncate the text.
3. Trim embed title and footer text
   Embed titles cannot exceed 256 characters. Footer text cannot exceed 2048 characters. Reduce these values if needed.

Fix 4: Remove Unsupported Characters

1. Escape special characters in JSON
   Double quotes inside a string must be escaped with a backslash: \". Newlines can be represented as \n. Backslashes themselves must be doubled: \\. Check your payload for unescaped characters.
2. Avoid unsupported Unicode
   Discord supports most Unicode characters, but some control characters (U+0000 to U+001F) are not allowed. Remove or replace them.

If the Error Persists After the Main Fix

Even after correcting the payload, you may still receive the error. Here are additional checks to perform.

Webhook URL Is Incorrect or Expired

Verify that the webhook URL is complete and includes the correct ID and token. A typo in the URL will cause a 404 or 400 error, which may appear similar. Copy the webhook URL directly from Discord Server Settings > Integrations > Webhooks.

Payload Contains Extra Fields

Discord ignores unknown fields but may reject the payload if a field has an unexpected type. For example, adding "tts": "yes" instead of "tts": true will fail because tts must be a boolean. Remove any fields you are not sure about.

Rate Limiting Is Not the Issue

If you send many requests quickly, Discord may return a 429 Too Many Requests error, not Invalid Form Body. The error message will clearly say 429. If you see 400 with Invalid Form Body, the problem is the payload, not the rate limit.

Discord Webhook Payload Fields: Required vs Optional

Field	Required	Max Length / Type
content	Yes, if no embeds are present	String, 2000 characters
embeds	Yes, if no content is present	Array of embed objects, max 10 embeds
embeds[].title	No, but at least one of title, description, or url is required per embed	String, 256 characters
embeds[].description	No	String, 4096 characters
embeds[].color	No	Integer (decimal color code)
embeds[].fields	No	Array, max 25 field objects

After fixing the payload, test the webhook by sending a simple message first. Use a tool like Postman or curl to send a POST request to the webhook URL with a minimal JSON body: {"content": "Test message"}. Once that succeeds, gradually add more fields. If the error reappears, check the field you just added. This incremental approach isolates the problem quickly.