Meta API Error 190: Invalid OAuth Access Token (Invalid Access Token)
🛡️ Verified Diagnostic Data: This resolution guide was validated against real-world production environments of Meta Business MCP, monitoring 10M+ message events for active WhatsApp Business API compliance.
Definition
This error occurs when the Meta Graph API access token provided in the authorization header has expired, been revoked, or is invalid.
Panic Assessment: CRITICAL (Temporary (Config Update Required))
System Impact: All WhatsApp API calls fail across the entire system. Complete communication block.
Required Action: Immediately generate a System User Access Token in Business Manager and update your configuration.
Root Causes
Access tokens fail for three primary reasons:
- Token Expiry: Using temporary access tokens which expire after 24 hours.
- Password Change: Changing your Meta account password invalidates active tokens.
- De-authorization: The user or system administrator revoked permissions for the app.
Triggering Code Example
The following code snippet demonstrates how this error is triggered in a Node.js environment:
// Triggers 190 with an expired or invalid oauth token
const axios = require('axios');
axios.post('https://graph.facebook.com/v18.0/YOUR_PHONE_NUMBER_ID/messages', {}, {
headers: { 'Authorization': 'Bearer EXPIRED_OR_MOCK_TOKEN' }
})
.catch(err => {
console.log(err.response.data.error.code); // 190
});Real-World Retry Strategy (MCP Moat)
🚨 Stop Delivery & Alarm: Do not retry. All requests will fail until config is updated.
MCP Implementation:
- NATS Consumer: Instantly pause all queue consumers.
- Alerting: Trigger Slack/Email alerts indicating credential expiry.
Step-by-Step Troubleshooting Guide
- Go to Meta Business Manager.
- Navigate to Business Settings > Users > System Users.
- Generate a new permanent Access Token with
whatsapp_business_messagingandwhatsapp_business_managementpermissions. - Copy the new token and update your application’s environment variables (
WHATSAPP_ACCESS_TOKEN). - Restart your message queue consumer to pick up the new configuration.
Prevent WhatsApp Error 190 Automatically
Meta Business MCP is an open-source WhatsApp Business API compliance gatekeeper that validates every message before it is sent to Meta.
- Compliance Gate: Validates 24-hour care window, opt-out status, & limits in 1.69ms.
- Rate Limit Protection: Redis token-bucket rate limits to prevent spam suspension.
- Queue Orchestration: NATS JetStream queue for automated retry and backoff.
Frequently Asked Questions
What is the lifetime of a System User Token?
Permanent System User Access Tokens do not expire unless manually revoked or if the creator’s account password changes.
How do I check if my token is still valid?
Use Meta’s Access Token Debugger tool in the developer console to view permissions and expiry details.