WhatsApp API Error Codes

Why broadcasts or automated messages fail, what common WhatsApp Cloud API error codes mean, and what you can do to fix them.

Short version: every message you send via Kraya is checked by Meta (WhatsApp). If you hit messaging limits, send too fast, use rejected templates, or message users who have blocked you, WhatsApp returns error codes like 131048 or 131049. This article explains the most common ones in plain English so your team and support bot know exactly what's going on.

1. How WhatsApp Cloud API Processes Your Messages

Whenever Kraya sends a message through the WhatsApp Cloud API, Meta performs several checks in this order:

• Account health check: looks at spam reports, blocks, and past behaviour.
• Messaging limits check: ensures you are within your daily messaging tier (250, 1K, 10K, etc.).
• User protection check: prevents users from being spammed by too many cold messages.
• Template & content check: verifies the template is approved and compliant with policies.
• Recipient check: confirms the number is valid, on WhatsApp, and hasn't blocked you.

If any of these checks fail, WhatsApp does not deliver the message and returns an error code. Kraya reads that code and marks the message as failed.

2. Most Common WhatsApp Cloud API Error Codes (Plain English)

Below are the most frequently seen error codes when sending via API providers. Use this like a dictionary: when you see a code in Kraya or from support, just scroll to that code here.

131048 — Messaging Limit Reached

What it means: you have hit the maximum messaging limit for your current tier (for example 250 messages in 24 hours). WhatsApp simply stops delivering additional messages in that rolling 24-hour window.

Why it happens:

• You sent too many broadcasts in a short period.
• Your account is still in the lower tier (e.g., 250) and you tried to send above that.

What you should do:

• Verify your business in Facebook Business Manager to unlock higher tiers (1K → 10K → 100K).
• Pause large campaigns for 24 hours until the limit resets.
• Start with smaller batches and increase gradually.

131049 — Not Delivered to Maintain Healthy Ecosystem Engagement

What it means: WhatsApp has temporarily stopped delivering your messages to protect users from potential spam. This usually shows up during heavy broadcast activity.

Why it happens:

• You are messaging too many cold users too quickly.
• Your recent campaigns got low engagement, blocks, or spam reports.

What you should do:

• Reduce broadcast size and spread messages over a longer time window.
• Use more value-driven, conversational templates (not aggressive sales).
• Allow 24 hours before retrying the same audience.

This is a hard platform limit; there is no hack or bypass. You can only adjust strategy and wait.

131040 — Template Not Approved or Flagged

What it means: the message template you are using is rejected, expired, or flagged for policy violation.

Why it happens:

• The template is still in rejected or pending state.
• The content violates WhatsApp policy (too promotional, misleading, or spammy).

What you should do:

• Open your WhatsApp Business / Meta panel and check the template status.
• Rewrite the template in simple, clear language and resubmit.
• Avoid all caps, fake urgency, and multiple emojis in a row.

131042 — Recipient Is Not on WhatsApp

What it means: the phone number you are trying to message is not registered on WhatsApp.

What you should do:

• Confirm the customer's number and country code.
• Clean your database and remove numbers that are not active on WhatsApp.

131021 — User Blocked Your Business

What it means: the user has blocked your business. WhatsApp will not deliver any further messages to them via API.

What you should do:

• Respect the user's choice and stop sending to this number.
• Review your messaging tone and frequency to avoid future blocks.

131026 — User Unreachable / Delivery Failed

What it means: WhatsApp could not deliver the message because the user is temporarily unreachable (device offline, network issues, or number recently changed).

What you should do:

• Retry after some time.
• If failures continue, verify if the number is still correct.

470 / 4700 — Bad Request or Invalid Parameters

What it means: there is a technical issue with the request itself – wrong template name, variable mismatch, or formatting issue.

Common causes:

• Number of variables in the template does not match the values you send.
• Wrong language code or template namespace.
• Incorrect JSON formatting by the integration.

What you should do:

• Double-check your template variables: {{1}}, {{2}}, etc.
• Ensure every placeholder has a corresponding value.
• If you are unsure, share the exact error and template with the Kraya support team.

1004 — Message Rate Too High

What it means: you are sending messages too fast and hitting WhatsApp's short-term rate limit.

What you should do:

• Reduce the size of each batch.
• Add small delays between messages or use Kraya's throttling settings (if enabled).
• Avoid firing multiple large campaigns at the same second.

1033 — Phone Number Not Approved / Not Connected

What it means: the phone number is not correctly connected to the WhatsApp Cloud API or the account is not fully approved.

What you should do:

• Verify the number connection in your WhatsApp Business / Meta dashboard.
• Reconnect the number via Kraya's integration flow.
• Make sure all verification steps and billing settings are complete.

200 — Permission Denied / Token Issue

What it means: the access token or credentials used to call the API are invalid or expired.

What you should do:

• Refresh your access token from Meta.
• Update the token in Kraya's WhatsApp integration settings.
• Retry sending once the token is updated.

1012 — Template Contains Unsupported Content

What it means: the template content is not allowed – for example:

• OTP-like content without the correct template category.
• Highly promotional or misleading offers.
• Prohibited content based on WhatsApp policy.

What you should do:

• Rewrite the template in neutral, clear language.
• Avoid exaggerated claims, spammy phrases, or forbidden topics.
• Resubmit the cleaned-up template for approval.

131044 — Out-of-Session Message (Non-template)

What it means: you tried to send a non-template message to a user after the 24-hour customer care window has expired.

What you should do:

• Use an approved template message to restart the conversation.
• Or wait for the user to send you a new message (which opens a fresh 24-hour window).

3. Quick Reference Table

4. How Kraya Helps You Reduce Message Failures

Once this article is added to your help centre and connected to the support bot, Kraya can:

• Read the error code returned by WhatsApp.
• Match it to this article and pull the correct explanation.
• Reply to the user with a clear reason and recommended action.

This way your team doesn't have to memorise Meta documentation, and customers get an instant, detailed answer instead of a generic "message failed" note.

5. FAQs – Real Questions Users Ask About Failed WhatsApp Messages

Q1. I tried to broadcast to 500 people but only ~120 messages were delivered. Why?

This usually happens when your account is in a lower messaging tier (for example 250 messages in 24 hours) and you attempt to send more than that. WhatsApp stops additional messages and returns errors such as 131048 or 131049. You can verify your business to increase the tier and split large broadcasts into smaller batches.

Q2. My template is approved but messages are still failing. What should I check?

First, confirm that you are using the correct template name and language. Then check that the number of variables in your template matches what you send from Kraya. If variables or formatting are incorrect, you will see errors like 470 or 4700. Fix the mapping and try again.

Q3. Why do messages fail only for some users and not everyone in the broadcast?

For a subset of users, one of the following is usually true:

• They have blocked your business number.
• Their number is not on WhatsApp anymore.
• Their account is temporarily unreachable or inactive.

In these cases, WhatsApp will not deliver your message even if the template and campaign are fine.

Q4. Why does WhatsApp put limits on how many messages my business can send?

Messaging limits protect users from spam and ensure a healthy ecosystem. Your tier automatically grows when you send high-quality messages that users respond to (rather than block or report). Accounts with better engagement gradually get access to higher limits.

Q5. How can I increase my WhatsApp messaging limit?

You can increase limits by verifying your business in Facebook Business Manager and maintaining good quality. As your account matures, limits move from 250 to 1,000, then 10,000 and beyond. Keep broadcasts relevant and avoid spammy templates to improve quality rating.

Q6. My promotional templates keep getting rejected. What am I doing wrong?

WhatsApp does not allow overly aggressive or misleading promotions. Avoid all caps, excessive emojis, or phrases that sound like spam ("WIN NOW", "LIMITED FREE OFFER!!!"). Instead, use clear, honest language that explains the benefit and gives users an easy way to opt out.

Q7. What should I do when I see error 131049 specifically?

Error 131049 means WhatsApp temporarily stopped your messages to maintain a healthy ecosystem. You should pause heavy campaigns, reduce the volume of cold outreach, and wait at least 24 hours before attempting again. Also, review your recent campaigns for high block or unsubscribe rates.

Q8. Can Kraya bypass or remove these WhatsApp platform limits?

No platform can bypass Meta policies. What Kraya does is help you work within those policies by sending smarter campaigns, warming up new numbers gradually, and giving you clear visibility into why a message failed so you can fix it quickly.

Tip for internal team: when you see an error code in logs, search this article by code (for example "131048" or "131049") and copy the explanation directly into your chat with the client or let the support bot fetch it automatically.