WhatsApp Template Media Upload Failures: Fix MIME and Size Errors

WhatsApp template media upload failures stop a project before it starts. You build a beautiful marketing or utility template. You add a header image or video. Then the API returns an error. These errors usually involve MIME types or file sizes.

This guide helps you fix these issues. You will learn the specific requirements for the Meta Graph API. You will also see how to use resumable uploads for better reliability.

Understanding WhatsApp Template Media Requirements

WhatsApp requires specific formats for template headers. If you send a file that the system does not recognize, the upload fails. This failure happens at the upload stage or during the template submission process.

Meta uses a two step process for template media. First, you upload the file to get a handle. Second, you use that handle in your template structure. Errors at either step prevent your message from reaching the customer.

Prerequisites for Successful Uploads

Before you start the code, check these requirements:

• A verified WhatsApp Business Account (WABA).
• A valid System User Access Token with whatsapp_business_management permissions.
• The App ID associated with your WhatsApp integration.
• A public URL or local file path for your media asset.

Fixing MIME Type Errors

WhatsApp supports a narrow list of MIME types. A MIME type tells the server what kind of file you are sending. If the file extension is .jpg but the content is actually a .webp file, the API rejects it.

Supported Image Types

Images in template headers must be one of these two types:

• image/jpeg (.jpg or .jpeg)
• image/png (.png)

WhatsApp does not support .webp, .gif, or .heic for template headers. If your source file is in one of these formats, convert it before uploading.

Supported Video and Document Types

Videos must use the video/mp4 format. Use the H.264 video codec and AAC audio codec for the best compatibility. Avoid high profile H.265 files as they often fail processing.

Documents must be application/pdf. While standard messages support .doc or .ppt, templates usually require PDF for the header component.

Resolving File Size Errors

Size limits depend on the media type. Exceeding these limits causes an immediate 400 Bad Request error.

Media Size Limits Matrix

• Images: Maximum 5MB.
• Videos: Maximum 16MB for templates.
• Documents: Maximum 100MB (though 16MB is safer for template headers).

If your video is 17MB, the upload fails. Use a tool like FFmpeg to compress the video. Lower the bitrate until the file falls below 16MB. For images, reduce the resolution or use a higher compression level in your image processing library.

Implementing the Resumable Upload Flow

Standard POST requests for large files often time out. Meta recommends the Resumable Upload API for media headers. This process involves three distinct steps.

Step 1: Initialize the Upload

You must tell Meta about the file before sending bytes. You send the file size and MIME type to receive an upload session ID.

{
  "file_length": 450000,
  "file_type": "image/jpeg",
  "access_token": "YOUR_ACCESS_TOKEN"
}

Send this to graph.facebook.com/v19.0/{APP_ID}/uploads. The response contains an ID that looks like upload:MTIzNDU....

Step 2: Upload the Binary Data

Use the session ID to push the actual file data. You must include the file_offset header. For the first chunk, the offset is 0.

curl -X POST "https://graph.facebook.com/v19.0/{SESSION_ID}" \
     -H "Authorization: OAuth YOUR_ACCESS_TOKEN" \
     -H "file_offset: 0" \
     --data-binary @your_image.jpg

Step 3: Retrieve the File Handle

If the upload succeeds, the response provides a h handle. This handle represents your file in the Meta ecosystem. Save this handle. You need it for the template creation API.

Practical Example in Node.js

This script demonstrates how to handle a file upload for a template header. It uses the fs module to read file stats.

const axios = require('axios');
const fs = require('fs');

async function uploadTemplateMedia(filePath, appId, token) {
    const stats = fs.statSync(filePath);
    const fileSize = stats.size;
    const fileType = 'image/jpeg';

    // 1. Initialize session
    const initRes = await axios.post(`https://graph.facebook.com/v19.0/${appId}/uploads`, null, {
        params: {
            file_length: fileSize,
            file_type: fileType,
            access_token: token
        }
    });

    const sessionId = initRes.data.id;

    // 2. Upload binary
    const fileData = fs.readFileSync(filePath);
    const uploadRes = await axios.post(`https://graph.facebook.com/v19.0/${sessionId}`, fileData, {
        headers: {
            'Authorization': `OAuth ${token}`,
            'file_offset': 0,
            'Content-Type': 'application/octet-stream'
        }
    });

    // 3. Return the handle
    return uploadRes.data.h;
}

Troubleshooting Common Error Codes

When your upload fails, the API returns a JSON error body. Look for these specific codes.

Error Code 100: Invalid Parameter

This code often means the MIME type is wrong. Check the file_type string in your initial request. Ensure it exactly matches the supported types like image/jpeg. Do not use image/jpg.

Error Code 1363019: File Size Too Large

This error confirms your file exceeds the limit. Check the file_length value. Ensure you calculate the length in bytes. One megabyte is 1,048,576 bytes.

Error Code 100: Upload Session Expired

Upload sessions expire after a few hours. If you initialize the upload but wait too long to send the binary data, the ID becomes invalid. Restart the process from Step 1.

Using WASender for Simpler Media Messaging

Some developers find the Meta Resumable Upload API too complex for simple projects. The official API has strict template approval rules. If you need to send media without creating approved templates, WASender is an alternative option.

WASender permits you to send media by connecting a standard WhatsApp account via QR code. It handles the media conversion internally. This removes the need for managing file handles or resumable upload sessions. While this is an unofficial method, it works well for internal tools or rapid prototyping where strict template compliance is not required.

Frequently Asked Questions

Why does my image look blurry in the template preview?

WhatsApp compresses images during the upload process. Use a source image with a resolution of at least 800x800 pixels. Avoid extremely high resolutions above 2000 pixels as the downscaling logic might introduce artifacts.

Is it possible to reuse a file handle for multiple templates?

Yes. A file handle remains valid for approximately 30 days. You are able to use the same handle in different template submissions or for different language variations within one template. This saves bandwidth and reduces API calls.

Does the file name affect the upload success?

Yes. Avoid special characters or spaces in the file name when using certain SDKs. Stick to alphanumeric characters and underscores. While the binary data is what matters, some headers fail if the filename in the multipart form is malformed.

What happens if I use the wrong MIME type for a video?

If you label an MP4 as an image/jpeg during the initialization step, the binary upload fails. The server expects data that matches the declared type. Always verify the file signature before starting the upload flow.

How do I fix the 'Invalid Header' error in the WhatsApp Manager?

This error occurs when the handle you provided does not match the media category of the template. If the template expects a Video header, but you provide a handle for an Image, the manager rejects the template. Ensure the header type in your JSON matches the file type of the handle.

Conclusion

Fixing WhatsApp template media upload failures requires attention to detail. Always verify your MIME types against the supported list. Keep your file sizes below the strict limits. Use the resumable upload flow for a more stable integration. By following these steps, you ensure your media headers load correctly every time. Your next step is to integrate the successful file handle into your template creation payload and send your first message.