WhatsApp API error code 3 is documented as "API Method — Capability or permissions issue." and returned with HTTP status 500
In plain terms: the request reached the endpoint, but your Meta app or its token is not allowed to perform that action.
Meta's public error-code reference could not be retrieved when this article was last checked, so the wording above is quoted from BSP documentation rather than from Meta. Confirm the current text against Meta's own reference before you build error handling on it.
What error code 3 means, and why the sources disagree
Error code 3 means the calling app lacks a capability or permission the endpoint requires, per the BSP documentation covering it. The recommended action: open Meta's Access Token Debugger, confirm whatsapp_business_management and whatsapp_business_messaging are on the token, and reissue the token if they are missing.
The conflict matters if you are writing error handling. One BSP table treats code 3 as a permission failure at HTTP 500. Another treats it as a recipient validation failure at HTTP 400. Both are secondary sources; neither is Meta.
We are not picking a winner, because that would mean asserting something we cannot verify. Treat the title as unreliable here and check the token first. If both permissions are present and the call still fails, capture the fbtrace_id and escalate to your provider.
The two permissions a WhatsApp app needs
A WhatsApp app normally needs two permission scopes: whatsapp_business_messaging and whatsapp_business_management. A scope is a named grant on an access token saying which actions that token may perform.
Messaging covers sending. Management covers account-level work, including template operations. Losing either produces an authorization failure, not a validation failure, so the request never gets far enough to tell you anything about your payload. A third scope, public_profile, is granted automatically at app creation and is not the one behind this failure.
Wati groups errors 200 to 299 as permission issues and advises re-granting the same two scopes, so the fix for the authorization family is that short list on a valid token. The walkthrough on setting up the WhatsApp Business API covers where tokens come from.
Standard Access vs Advanced Access
Standard Access lets your app act only for test users, developers and admins explicitly added to the app. Advanced Access, granted after App Review, lets the app act for any user who grants the permission. Production traffic needs Advanced Access.
Factor | Standard Access | Advanced Access |
|---|---|---|
Who the app can act for | Test users, developers and admins added to the app | Any user who grants the permission |
App Review required | No | Yes, submission is mandatory |
Typical use | Development and internal testing | Live customer traffic |
Scopes to request |
| Same two scopes, at the advanced tier |
| Granted automatically at app creation | Granted automatically at app creation |
The usual failure mode: a team tests under Standard Access, adds a real customer number, and sees authorization errors on calls that worked yesterday. The code did not change; the account on the other side was never inside the app's allowed set. Plan your WhatsApp API integration around that boundary.
What App Review actually asks for
App Review asks for evidence that your app uses the permissions it requests. Twilio's Tech Provider guide tells developers to request advanced access for whatsapp_business_messaging and whatsapp_business_management, states that an App Review submission is mandatory, and specifies screen recordings showing message sending and template creation
Prepare two recordings before you submit:
- Your app sending a WhatsApp message end to end.
- Your app creating a message template.
Review timelines and approval rates are not published by any source we could verify, so treat the submission as work of unknown duration. The primer on WhatsApp message templates explains what the reviewer will watch you create.
Diagnosing error code 3 in five minutes
Start with the token, where the documented cause lives. No code change required.
- Open the Access Token Debugger. Paste the token production actually uses, not one from your notes.
- Read the scopes list. Confirm both
whatsapp_business_messagingandwhatsapp_business_managementare present. - Check the app and expiry. Confirm the token belongs to the Meta app you expect and has not expired.
- Regenerate if a scope is missing. Issue a new token with both scopes (Heltar, retrieved 2026-08-24).
- Do not loop on retries. Dualhook classifies auth failures including 0, 10, 190 and 200 as non-retryable: a retry that changes neither the token nor its permissions cannot succeed (Dualhook, retrieved 2026-08-24). Treat code 3 the same way.
A minimal template send:
curl -X POST "https://graph.facebook.com/v<VERSION>/<PHONE_NUMBER_ID>/messages" \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"to": "<RECIPIENT_WA_ID>",
"type": "template",
"template": {
"name": "<TEMPLATE_NAME>",
"language": { "code": "<LOCALE>" }
}
}'If that succeeds with a fresh token carrying both scopes, the token was the problem. If it fails identically, the cause sits at app or account level and needs your provider. With a WhatsApp chatbot integration, also check the automation layer uses the current token, not one cached at deploy time.
Branch on the numeric code, not the status or the title
Build error handling on the numeric code and the details field in the response, never on the HTTP status or the human-readable title. Both MessageBot and Wati advise this, and code 3 is the clearest argument for it in the whole table.
Consider a status-first handler. An HTTP 500 normally reads as "the server had a problem, retry with backoff". For code 3 that is wrong twice over: the cause is a permission grant on your side, and retrying cannot fix it.
A permission problem arriving as a 500 is not the contradiction it looks like. Status codes describe transport-layer outcomes; Meta's Graph API family carries its own error taxonomy in the response body. The two need not line up. Read the numeric code and the error_data or details field, and keep the fbtrace_id for escalation
In practice: a switch on the code value, a whitelist of retryable codes, and an explicit non-retry path for the authorization family. The same discipline is why WhatsApp API rate limits deserve their own branch.
Related authorization errors
Code 3 sits in a family of authorization failures sharing one diagnostic path: check the token, check the scopes, do not retry blindly.
Code | Documented description | HTTP status | Retry? |
|---|---|---|---|
3 | "API Method — Capability or permissions issue."; "Recipient is the sender" | 500 (Heltar) / 400 (MessageBot), disputed | No |
10 | "Permission is either not granted or has been removed." | 403 per MessageBot; Heltar states none | No |
200 | "API Permission — Permission is either not granted or has been removed." | 403 (Heltar) | No |
0 | Not covered by the sources we could reach | Not published | No |
190 | Not covered by the sources we could reach | Not published | No |
Codes 10 and 200 carry an identical documented description, worth knowing before you write two handlers for them. Articles on errors 10, 200, 0 and 190 and the 200 to 299 range are in preparation and appear here as plain text only.
Once the token is ruled out, check account-level configuration such as running multiple numbers on one WhatsApp Business account and your WhatsApp API compliance posture. Access model matters when choosing a WhatsApp API provider too.
Frequently Asked Questions
Why do I get WhatsApp API error code 3?
Because your app or access token lacks a capability or permission the endpoint requires. The BSP documentation covering this code says to check the token in Meta's Access Token Debugger for the two WhatsApp scopes. A second BSP table gives the same code a different meaning, so verify against Meta's own reference and read the details field in your response.
Which permissions do I need for the WhatsApp Business API?
Two scopes: whatsapp_business_messaging and whatsapp_business_management. Messaging covers sending. Management covers account-level operations including templates. Both should appear on the token you use in production, and both are what BSP guidance tells you to re-grant when permission errors appear. A third scope, public_profile, is granted automatically at app creation, so you never request it.
Do I need App Review for WhatsApp?
Yes, if you need Advanced Access. Standard Access only lets your app act for test users, developers and admins added to the app, which rules out real customer traffic. Twilio's Tech Provider guide states that an App Review submission is mandatory and requires screen recordings showing message sending and template creation. Prepare those recordings first.
Is error 3 the same as error 10?
No. Codes 10 and 200 share one word-for-word identical documented description about permission not being granted or having been removed. Code 3 is documented differently, as a capability or permissions issue on the API method, and it is the code where BSP sources disagree with each other. Separate articles on error 10 and error 200 cover those codes.
Why does a permission problem return HTTP 500?
Because HTTP status and application error code describe different layers. The status reflects the transport-layer outcome, while Meta's Graph API family carries its own error taxonomy in the response body, and the two need not agree. A 500 on a permission failure looks contradictory but carries no useful information. Branch on the numeric code and details field, and do not auto-retry.
Getting WhatsApp authorization right the first time
Permission errors at go-live are usually an access-model problem, not a code problem, and they are cheaper to solve before launch. Helo.ai is a Meta Partner and Google RCS Anchor Partner of the Year, bringing 25 years of enterprise communication experience to AI-first messaging for India-first businesses. Talk to an expert about your access model and App Review preparation.
