This article covers the errors you may encounter when using the WhatsApp Public API, how quality ratings and messaging tiers affect your sending capability, and what can be resolved by you versus what requires action from Meta or Aircall Support.
Error reference
| Error | What it means | What to do |
|---|---|---|
| 403 | Account is on Essentials, has no active WhatsApp add-on, or the feature is not enabled | Confirm plan and add-on status in the Aircall dashboard. Please contact Aircall Support to check the feature is available on your plan. |
| 400 — line not configured | The line has not been registered for Public API use | Call POST /v1/numbers/{id}/messages/configuration first. |
| 400 — template not approved | The template being sent is not in APPROVED status in Meta | Check template status in Meta Business Manager. This cannot be resolved by Aircall. |
| 63016 — 24-hour window expired | The send returns a 200 response, but your webhook receives a callback with an error when free-form text is sent outside the conversation window | Use an approved template to re-initiate a conversation with your customer. See the 24-hour window section in the Getting started with the Whatsapp Public API article. |
| 400 — WABA not configured | The WhatsApp line does not have a WABA (WhatsApp Business Account) set up | Please contact Aircall Support. This is a line configuration issue. |
| 400 — line OFFLINE or BLOCKED | The line is not in an active sending state | Check the line health endpoint. If BLOCKED, Please contact Aircall Support. |
| 429 | Messaging tier limit exceeded: daily conversation cap reached | Meta-imposed limit. Resets every 24 hours. Cannot be overridden by Aircall. |
| 131048 | Meta spam rate limit: sends from this number are restricted by Meta | Review your messaging quality and contact Meta Business Support. Aircall cannot override this. |
| 131045 | Phone number registration error with an external provider | Please contact Aircall Support |
| 131000 | Unknown Meta error | If the error persists, Please contact Aircall Support with your company ID, line ID, the full error payload, and a timestamp. |
The 24-hour conversation window
WhatsApp's conversation window is a Meta rule, not an Aircall setting. It controls when free-form text messages can be sent.
- A 24-hour window opens when a customer messages your number, or when they reply to one of your messages.
- Within that window, you can send free-form text.
- Once the window closes, you can only send an approved template to re-start the conversation.
IMPORTANT: Attempting to send free-form text outside an open window will return an error to your webhook. The solution is always to send an approved template first. Aircall cannot override or extend the window.
Quality rating
Meta assigns each WhatsApp line a quality rating based on how recipients respond to messages from that number. If recipients frequently block or report your number, the rating degrades.
- GREEN: line in good standing, no sending restrictions.
- YELLOW: quality is degrading, often because customers are reporting your messages as spam or blocking your number. Review template quality and consider reducing send volume.
- RED: Meta has restricted this line. Sends may fail. Contact Meta Business Support.
IMPORTANT: Quality ratings are set and controlled by Meta. Aircall cannot change them. Improving your rating requires better templates, cleaner contact lists, and confirmed opt-ins from recipients.
Messaging tiers
Meta limits the number of business-initiated conversations a line can start per 24-hour period. This is the messaging tier. Tiers increase automatically as Meta gains confidence in a number's quality and sending patterns. There is no manual process to request a tier increase.
| Tier | Conversations per 24 hours | Typical account type |
|---|---|---|
| TIER_250 | 250 | New or unverified lines |
| TIER_1K | 1,000 | Standard verified businesses |
| TIER_10K | 10,000 | Established, high-quality senders |
| TIER_100K | 100,000 | High-volume verified businesses |
NOTE: If your integration returns a 429 error, the daily tier limit has been reached. The limit resets every 24 hours. Build retry logic into your integration for this case.
What you can and cannot control
Some limitations are set by Meta and cannot be changed by Aircall or by you.
The following cannot be overridden by anyone at Aircall:
- Quality ratings
- Messaging tier limits
- Unblocking a number that Meta has restricted
- Approving or rejecting WhatsApp message templates
- The 24-hour conversation window
Contact Aircall Support for:
- Feature status check or activation
- WABA not configured errors (400)
- Lines that are OFFLINE or BLOCKED
- Phone number registration errors (131045)
- Persistent unknown errors (131000): provide your company ID, line ID, full error payload, and timestamp
Contact Meta Business Support directly for:
- Spam rate restrictions (131048)
- Quality rating degradation
- Lines fully blocked by Meta
FAQs
My API calls are returning a 403 even though we have a WhatsApp add-on. What's wrong?
A 403 can also mean the feature is not yet enabled for your account, or that your plan is Essentials. Please contact Aircall Support to confirm all eligibility conditions are met: Pro plan or above, active WhatsApp add-on, and the line is registered.
Can I send a message to a customer who has never messaged us first?
Yes, use an approved template. Approved templates can be sent outside the 24-hour window to initiate contact. Free-form text messages require an open conversation window, meaning the customer must have messaged you or replied within the last 24 hours.
Why is my line showing a YELLOW or RED quality rating?
Meta degrades quality ratings when recipients block or report messages from your number. This typically results from sending unsolicited messages, using low-quality templates, or messaging contacts who have not opted in. Aircall cannot change this rating. Improve your messaging practices and allow time for the rating to recover naturally.
How quickly do messaging tier limits reset?
Every 24 hours from the point the limit was reached. If you receive a 429 error, wait 24 hours before retrying. Tiers increase automatically over time as Meta gains confidence in your sending quality.
We want HubSpot or Salesforce to send WhatsApp messages automatically. Where do we start?
Start with the getting started article linked below. Once your line is registered, your CRM or RevOps team can build workflows that call POST /v1/messages/whatsapp/send when deal stages change, contracts are ready, or other trigger events fire.