Understanding Errors
When a message fails, the portal gives you detailed information about what went wrong and what you can do about it. This page explains the error categories and how to use the Error Info dialog.
Error Categories
Every failed message is classified into one of three categories:
Retryable Errors (Green)
These are temporary issues that may resolve on their own. The message can be sent again.
| Error | What happened |
|---|---|
| Rate limit reached | WhatsApp temporarily limited your sending speed |
| Server unavailable | WhatsApp's servers were briefly unavailable |
| Timeout | The message took too long to process |
| Temporary network issue | A connection problem occurred during sending |
Most retryable errors resolve quickly. The automatic retry system will attempt to resend these messages for you — no action needed in most cases.
Non-Retryable Errors (Red)
These are permanent failures. The message cannot be sent again to this contact with the same content.
| Error | What happened |
|---|---|
| Invalid phone number | The number doesn't exist or isn't registered on WhatsApp |
| Customer opted out | The recipient has blocked your business or opted out of messages |
| Template rejected | The message template was rejected by WhatsApp after sending |
| Account suspended | Your WhatsApp Business Account has been restricted |
| Media unavailable | An attached image, video, or document could not be accessed |
Non-retryable errors usually require you to fix the underlying issue (update the contact's number, use a different template, etc.) rather than simply retrying.
Business Logic Errors (Yellow)
These are business rule violations — the message was blocked by a policy or limit, not a technical issue.
| Error | What happened |
|---|---|
| Daily sending limit reached | You've hit your daily message quota |
| Template paused | The template has been paused due to low quality |
| Outside messaging window | The 24-hour messaging window has expired and no template was used |
| Insufficient balance | Your account doesn't have enough credit to send |
Some business logic errors can be retried once the condition changes (e.g., after the daily limit resets), while others need manual intervention.
Error Info Dialog
Click the info icon (ⓘ) next to any error name in the message list to open the Error Info dialog. This dialog explains the error in plain language.
2. Capture the Error Info dialog showing all sections
Save to:
static/img/screenshots/failed-messages/error-details/error-info-dialog.pngThe dialog includes these sections:
What Happened
A clear, simple explanation of the error. No technical jargon — just a plain description of what went wrong.
Why It Happened
The likely cause of the failure, helping you understand the root issue so you can decide what to do next.
What To Do
Specific, actionable steps you can take to resolve the issue. This might be:
- Wait and retry later
- Update the contact's information
- Check your account settings
- Contact support
Countdown Timer
If the error is retryable, a countdown timer shows how much time is left before the message is eligible for retry. Once the countdown reaches zero, you can retry the message.
2. Capture the countdown timer showing the remaining time
Save to:
static/img/screenshots/failed-messages/error-details/countdown-timer.pngCopy Details
Click the Copy Details button to copy the full error information to your clipboard. This is useful when you need to share the error details with support or a team member.
Learn More
A Learn More link takes you to additional information about the specific error code, including troubleshooting steps and best practices.
Reading Error Details in the Table
Even without opening the dialog, you can quickly assess errors from the message list:
| What to look at | What it tells you |
|---|---|
| Error name | A short description of what went wrong |
| Category badge | Whether it's retryable (green), non-retryable (red), or business logic (yellow) |
| Info icon (ⓘ) | Click for full details |
| Countdown | How long until the message is eligible for retry |
| Retry attempt badge | How many times the message has already been retried |
Common Error Codes
Here are some of the most common errors you'll encounter:
| Error | Category | What to do |
|---|---|---|
| Rate limit exceeded | Retryable | Wait for the countdown and retry, or let the automatic system handle it |
| Server error | Retryable | Usually resolves on its own — the automatic system will retry |
| Invalid number | Non-Retryable | Verify and update the contact's phone number |
| Recipient opted out | Non-Retryable | The customer has blocked messages — do not retry |
| Template paused | Business Logic | Check the template status in WhatsApp Templates and fix quality issues |
| Daily limit reached | Business Logic | Wait for the daily limit to reset (usually at midnight) |
| Insufficient balance | Business Logic | Add credit to your account, then retry |
| Media not found | Non-Retryable | Re-upload the media file and send a new message |
Error codes and descriptions may vary depending on your WhatsApp Business setup. The Error Info dialog always provides the most up-to-date explanation for each specific error.