WhatsApp error 131053 (media upload error): find the bad file and fix it

WhatsApp error 131053 means WhatsApp could not upload the media you attached to a message. Meta's error reference describes it as "Unable to upload the media used in the message" and adds: "The media could not be uploaded for one or more reasons, such as an unsupported media type." Meta's suggested fix is to read error.error_data.details in the messages webhook for the failed message, inspect the file, and "confirm that they are in fact supported". In practice the file is the wrong type, too big, or not reachable from Meta's servers.

Who sees this error

Anyone sending an image, video, audio, document or sticker through the Cloud API, whether in a free-form reply inside the 24-hour customer service window or in a message template with a media header. It is not related to your quality rating or messaging limit, and other text messages from the same number keep working. Do not confuse it with 131052, which is the reverse: media sent to you by a customer that the API could not download.

The usual causes

Supported media at a glance

These are the Cloud API limits from Meta's media reference. Check the page before quoting exact values elsewhere, because Meta updates it.

Uploaded media IDs are kept by Meta for 30 days. After that, an old ID is rejected and you must upload again.

What the failure looks like

When you send by link, the API usually accepts the request, and the failure comes back in the status webhook a moment later. Illustrative payload (title and details text vary):

{
  "statuses": [
    {
      "id": "wamid.HBgMOTE5ODI5MDAxMjM0FQIAERgSQzVF...",
      "status": "failed",
      "timestamp": "1761985800",
      "recipient_id": "919829001234",
      "errors": [
        {
          "code": 131053,
          "title": "Media upload error",
          "message": "Media upload error",
          "error_data": {
            "details": "Downloading media from weblink failed with http code 403, status message Forbidden"
          }
        }
      ]
    }
  ]
}

The details string is the most useful part of this error. An HTTP code such as 403 or 404 points to the link; a phrase about an unsupported or unknown type points to the file itself.

Step-by-step fix

1. Read the details. Log errors[0].error_data.details from the webhook, not just the code.
2. Fetch the link the way Meta does. From a server with no cookies, run curl -I "https://cdn.example.in/banner.jpg". You want status 200 and a content-type such as image/jpeg. A 302 to a login page, 403, 404 or text/html explains the failure.
3. Check the real type. Download the file and run file -I banner.jpg (macOS) or file --mime-type banner.jpg (Linux). Meta's reference gives exactly this check: file -I rejected-file.mov.
4. Check the size against the table above.
5. Convert if needed. A MOV or an HEVC video can be converted with ffmpeg -i input.mov -c:v libx264 -c:a aac -movflags +faststart output.mp4. An HEIC photo can be exported as JPEG from the phone or converted on a computer.
6. Host it properly or upload it. Either serve the file from a public HTTPS URL with the right Content-Type, or upload it to POST /<PHONE_NUMBER_ID>/media and send the returned id instead of a link.
7. Send one test message to your own phone before resending to the whole audience.

A worked example

Priya runs marketing for Rangoli Home, a home-decor brand in Jaipur. She schedules a template with a video header showing the new block-print bedsheets (₹2,349) to 1,800 opted-in customers. Every send fails with 131053. The video was shot on an iPhone and uploaded to the brand's website as bedsheet-launch.mov, 19 MB.

Two problems, both visible in a minute: file -I reports video/quicktime, which is not on Meta's list, and the file is over 16 MB. Her developer converts it with the ffmpeg command above, trims it to 30 seconds so it comes down to about 9 MB, uploads it to the media endpoint and resends. Meta charges only for delivered messages, so the 1,800 failed sends did not cost anything, but the launch went out two hours late. The team now runs file -I and a size check on every campaign asset.

Preventing 131053

• Validate before you send. Check type and size when a file is added to your system, not when the campaign starts.
• Prefer media IDs for repeated sends. Upload once, reuse the ID for up to 30 days, and re-upload before it expires.
• Never send share pages. Drive, Dropbox and WhatsApp Web links are pages, not files.
• Set Content-Type on your storage. Object storage often defaults to application/octet-stream when the type is not set at upload.
• Keep a test step. One message to an internal phone catches format problems for free.

How Broadchat handles media

Files you upload in Broadchat (in the Inbox, campaign headers, chatbot steps or templates) are uploaded to Meta and sent by media ID. The ID is cached for each file and phone number for about 25 days, inside Meta's 30-day window. If Meta rejects a cached ID, Broadchat drops it, uploads the file again and retries once, and if that still fails it sends the file by link. External links that you paste are sent to Meta as they are, so they must be public and correctly typed. When a send still fails, the message shows the reason "The media could not be uploaded or downloaded." and the code 131053 in message info. In Campaigns, a template with a media header cannot be launched until you upload the file or paste its URL.

For the full list of codes see the WhatsApp API error codes cheat-sheet. Template sends that fail because of the template itself are covered in error 132001 and error 132000. New to the platform? Start with what the WhatsApp Business API is.