Authorization Errors

Authorization errors occur when the API cannot authenticate your app or access token, or when the required permissions are not granted. These errors are typically returned as HTTP 401 Unauthorized or HTTP 403 Forbidden responses.

Meta recommends building error-handling logic around the 'code' value and 'details' payload property rather than on error titles, as titles may be deprecated in future API versions.

⚠️⚠️ Note: Businesses using Chakra Chat solution may not be able to resolve the issue directly.
Reach out to Chakra team to troubleshoot this issue via a Chakra Ticket.

Error 0 - AuthException

Unable to Authenticate App User

ERROR CODE

0

ERROR SUMMARY

AuthException — Unable to Authenticate App User

ERROR DESCRIPTION

This error is returned when the WhatsApp Cloud API cannot authenticate the app user making the request. The most common cause is an expired, invalidated, or revoked access token. It may also occur if the app user has changed a privacy setting that prevents all third-party apps from accessing their data.

HTTP Status: 401 Unauthorized. This error is returned synchronously in the Graph API response.

RESOLUTION & TROUBLESHOOTING STEPS

1. Check the expiry of your access token. System User access tokens can be long-lived, but may still expire or be invalidated.

2. Navigate to the Meta App Dashboard and generate a new access token. For production environments, use a System User access token via the Business Manager.

3. If you are using a short-lived token (e.g., from OAuth login), implement a token refresh flow or switch to a long-lived system user token.

4. Verify in the Meta App Dashboard that the app user has not revoked access to your application.

5. Test the new token using the Access Token Debugger at https://developers.facebook.com/tools/debug/accesstoken before re-deploying.

OTHER NOTES

In Chakra Chat, access tokens are configured under Settings → WhatsApp Configuration → API Credentials. Ensure the token displayed has not expired.

For high-volume production accounts, always use permanent System User access tokens rather than temporary user tokens to avoid unexpected authentication failures.

Error 3 — API Method

Capability or Permissions Issue

ERROR CODE

3

ERROR SUMMARY

API Method — Capability or Permissions Issue

ERROR DESCRIPTION

This error indicates a capability or permissions problem with the app making the request. The app may not have been granted the specific permissions required by the endpoint being called. This is typically returned with HTTP 500 Internal Server Error.

Common scenarios include calling an endpoint that requires the 'whatsapp_business_messaging' permission that has not yet been approved for your app, or using an endpoint that is only available to verified Tech Providers or Solution Partners.

RESOLUTION & TROUBLESHOOTING STEPS

1. Open the Access Token Debugger (https://developers.facebook.com/tools/debug/accesstoken) and inspect which permissions are currently granted to your access token.

2. Compare the granted permissions against those required by the endpoint you are calling. The WhatsApp Cloud API typically requires 'whatsapp_business_messaging' and 'whatsapp_business_management'.

3. If a required permission is missing, request it through the Meta App Review process in the App Dashboard under App Review → Permissions and Features.

4. If you are a Tech Provider or Solution Partner, verify that your partnership status is active and that the relevant capabilities have been enabled.

OTHER NOTES

This error code (3) maps to the Graph API 'API Method' error, which is a broad category. Always inspect the 'details' field in the error response for specifics.

App Review for production WhatsApp API access can take several business days. Ensure your app is not in Development mode when going live.

Error 10 - Permission Denied

Required Permission Not Granted or Removed

ERROR CODE

10

ERROR SUMMARY

Permission Denied — Required Permission Not Granted or Removed

ERROR DESCRIPTION

Permission is either not currently granted to the access token being used, or it was previously granted but has since been removed. This error is returned with HTTP 403 Forbidden.

This error also occurs for WhatsApp Flows with Endpoint if the phone number used to set the business public key has not been allowlisted. Additionally, if your account is not eligible to access certain API endpoints (e.g., endpoints in private beta), you will receive this error.

RESOLUTION & TROUBLESHOOTING STEPS

1. Use the Access Token Debugger to confirm which permissions are attached to your token.

2. If you are using WhatsApp Flows with an endpoint, verify that the business phone number used when setting the public key has been added to the allowlist.

3. Check whether the endpoint you are calling has specific eligibility criteria (e.g., it may be restricted to Solution Partners or WABA accounts with a certain tier).

4. Re-request any revoked permissions through the Meta App Dashboard and ensure App Review approval is current.

OTHER NOTES

In Chakra Chat, if you see this error on outbound messages, check that your connected phone number's WABA has the 'whatsapp_business_messaging' permission active.

This error is distinct from Error 131005 (Access denied), which is also a 403 but is specific to the Cloud API layer rather than the Graph API permission layer.

Error 190 - Access Token Expired

ERROR CODE

190

ERROR SUMMARY

Access Token Has Expired

ERROR DESCRIPTION

The access token provided in the API request has expired. This is a specific sub-type of authentication failure that occurs when a previously valid token's expiry timestamp has passed. Returned as HTTP 401 Unauthorized.

Short-lived user access tokens (valid for ~1–2 hours) and long-lived tokens (valid for ~60 days) both expire. System User tokens can also expire depending on how they were configured.

RESOLUTION & TROUBLESHOOTING STEPS

1. Generate a new access token. For a System User token, go to Meta Business Suite → Settings → System Users → Generate New Token.

2. Update the token in your Chakra Chat configuration immediately. Navigate to Settings → WhatsApp Configuration → API Credentials and paste the new token.

3. To prevent future occurrences, implement token expiry monitoring. Set up an alert when the token is within 7 days of expiry.

4. For automated systems, consider using the OAuth token refresh endpoint to programmatically renew tokens before they expire.

OTHER NOTES

Chakra Chat will surface token expiry warnings in the platform notifications panel when the connected token is approaching its expiry date.

Unlike error code 0 (which is broader), error 190 specifically means expiry — not revocation. If you generate a new token and still see this error, the system clock on the server generating the token may be incorrect.

Error 200–299 - API Permission

Permission Not Granted or Removed

ERROR CODE

200–299

ERROR SUMMARY

API Permission — Permission Not Granted or Removed

ERROR DESCRIPTION

Error codes in the 200–299 range all represent API Permission errors at the Graph API level. These indicate that the required permission for the endpoint is either missing from the access token's granted scopes, or it was granted but has since been removed.

HTTP Status: 403 Forbidden. These are broad Graph API permission errors that wrap the underlying WhatsApp permission requirements.

RESOLUTION & TROUBLESHOOTING STEPS

1. Use the Access Token Debugger to review all currently granted permissions on your token.

2. Identify which specific permission corresponds to the endpoint you are calling. Refer to the WhatsApp API permissions documentation at https://developers.facebook.com/documentation/business-messaging/whatsapp/permissions.

3. Submit an App Review request if the required permission has not been granted, or resubmit if it was removed due to policy violations.

4. Ensure your app is in Live mode (not Development mode) for production use cases — some permissions are not available in Development mode.

OTHER NOTES

The specific error code within the 200–299 range can help narrow down the permission involved. Refer to the Graph API error documentation for the exact permission mapping.

Permissions can be revoked by Meta during policy enforcement reviews. If this happens, you will receive a notification in the Meta App Dashboard.