This guide lists the most common error codes returned by the WhatsApp Business API and provides immediate corrective actions for each case.

When a message send fails, the system returns a log with details. To diagnose the issue, focus on the code field (inside the errors object).
Below, find the corresponding error code to understand what happened and how to resolve it.

Error List and Solutions

Error 131030: Invalid Recipient

What it means:
The phone number you tried to message is not a valid WhatsApp account or does not exist.

Recommended action:

• Check if the number is in the correct format (Country Code + Area Code + Number).
• Confirm with the customer that they have an active WhatsApp account.

Important:
Remove this number from your sending list. Repeatedly messaging invalid numbers harms your account reputation.

Error 131047: 24-Hour Window Closed

What it means:
More than 24 hours have passed since the customer’s last message. According to Meta rules, free-form session messages cannot be sent after this period.

Recommended action:

• Do not resend the same message.
• Send an approved Message Template to reopen the conversation. Once the customer replies, the 24-hour window is renewed.

Error 131026: Message Not Delivered (Policy Violation)

What it means:
The message could not be delivered. This usually occurs because the user blocked the business or the content violates a specific policy.

Recommended action:

• Check if the template content was recently changed.
• If the error occurs for a single customer, it is likely they blocked your number. Stop messaging this contact.

Error 130429: Rate Limit Reached

What it means:
Your business has reached its daily message limit (Tier) or sent messages too quickly within a short period.

Recommended action:

• Check which Tier your account is in (e.g., 1,000 or 10,000 messages/day).
• Reduce sending speed.
• Wait a few hours before attempting new sends.

Error 131042: Payment Failure

What it means:
There is a billing issue with the ad account associated with WhatsApp Business (card declined, insufficient funds, or missing payment method).

Recommended action:

• Immediately access Business Manager > Billing and resolve the payment issue.
  Messaging services will remain paused until payment is settled.

Error 131049: Quality Block (Spam)

What it means:
Meta has blocked sending to protect system integrity, usually due to a high volume of recent user reports or blocks.

Recommended action:

• Stop all sends immediately.
• Do not insist—sending more messages may permanently ban your number.
• Review your strategy and wait 24–48 hours, sending only essential utility templates.

Error 131051: Unsupported Media Type

What it means:
The file sent (PDF, image, video) is too large, corrupted, or in an unsupported format.

Recommended action:

• Check file size (16MB limit for general media, 100MB for documents).
• Convert files to standard formats (JPG, PNG, PDF, MP4).

Error 132000: Parameter Error (Variables)

What it means:
The number of variables sent via the API does not match the number defined in the template.

Recommended action:

• Compare your payload with the template in the Manager.
  If the template expects 3 variables ({{1}}, {{2}}, {{3}}), your JSON must include exactly 3 populated parameters.

Error 132001: Template Not Found

What it means:
The system could not find a template with the specified name.

Recommended action:

• Check the exact template name (must be lowercase with underscores, e.g., order_confirmation).
• Verify the language code (e.g., pt_BR).
• Confirm in the Manager that the template status is APPROVED.

Error 131031: Account Blocked

What it means:
The WhatsApp Business Account (WABA) has been restricted due to severe policy violations.

Recommended action:

• Access Account Quality in Business Manager to review the reason and submit an appeal.

Error 131048: Spam Rate Block

What it means:
Unlike a general quality block, this error indicates that a specific spam-report threshold was reached in a short period.

Recommended action:
Stop sending immediately. Review the last campaign—your message may be confusing users or lacking a clear opt-out option.

Error 131056: Per-User Message Limit (Pair Rate Limit)

What it means:
Too many messages were sent to the same recipient in a short time, triggering a temporary block for that specific user.

Recommended action:
Wait a few minutes before sending another message to this customer. Avoid “bombarding” users with multiple consecutive messages.

Error 368: Temporary Policy Block

What it means:
The WhatsApp Business account was temporarily blocked due to violations detected by automated integrity systems.

Recommended action:
Check the Account Quality panel in Business Manager. This block usually lasts 24 hours or until the indicated issue is resolved.

Technical and Configuration Errors

Error 133010: Sender Not Registered

What it means:
The issue is with your business number. It is not properly registered with the API or lost its connection.

Recommended action:
Redo the number registration via the API (POST /register) or disconnect and reconnect the number in your BSP/integration panel.

Error 131000: Generic Error (Something went wrong)

What it means:
A temporary technical failure on Meta’s servers. This is not caused by your request.

Recommended action:
Wait a few minutes and retry. If it persists for hours, open a support ticket with Meta.

Error 131053: Media Upload Failed

What it means:
The media file could not be processed due to unsupported format, corruption, or excessive size.

Recommended action:
Try opening the file locally. Ensure it meets size limits (16MB for images/videos, 100MB for documents) and convert to standard formats (JPG, MP4, PDF).

Error 131008 / 131009: Missing Required Parameter

What it means:
Your API request is incomplete.

• 131008: A required field is missing.
• 131009: A provided value is invalid.

Recommended action:
Review your JSON payload. Ensure required fields such as type, to, and template are correctly filled and free of typos.