Troubleshooting | WhatsApp

MISSING_ACCESS_TOKEN
No accessToken could be resolved — neither a vault credential nor the inline accessToken config field had a value.
Fix: Set the inline field for testing, or configure a vault credential for production. See Authentication & Setup.

MISSING_PHONE_NUMBER_ID
The operation requires phoneNumberId but it was left blank.
Fix: Copy the Phone Number ID from Meta's API Setup page (or your registered number's details) into the phoneNumberId field. Note that catalog/business-account-scoped commerce and template-management operations don't need this field — see Authentication & Setup.

MISSING_FIELD: <fieldName>
A required operation-specific field (e.g. to, text, templateName) was empty.
Fix: Check that resource's operations page for the exact required-field list.

Recipient number rejected / message not delivered
WhatsApp phone numbers must be in E.164 format (+ followed by country code and subscriber number, digits only).
Fix: Normalize numbers to E.164 before calling any message or group operation.

HTTP 429 (rate limited)
Meta's Graph API enforces per-app and per-number rate limits.
Fix: Nothing to do manually for occasional bursts — WhatsAppRateLimitHandler automatically retries up to MaxRateLimitRetries times using the Retry-After header. If you see 429s surfacing anyway, you've exhausted the retry budget; reduce request volume or raise MaxRateLimitRetries/MaxRateLimitDelaySeconds. See Configuration.

Template message rejected as "not approved"
A template created via template/create must clear Meta's review before it can be sent.
Fix: Poll template/get or template/list for approval status before calling send.

Media upload rejected for size
The file exceeds MaxMediaUploadSizeBytes (default 16 MB, matching WhatsApp's own limit).
Fix: Compress or transcode the file before uploading, or host it externally and use mediaUrl instead of mediaId where the operation supports it.

"Operation 'X' is not yet implemented" (not_implemented)
message/send-and-wait and all Trigger operations (TRG01-TRG07, inbound webhook events) are routed but have no implementation yet.
Fix: See Roadmap for what's planned.

unsupported_operation
The resource/operation pair doesn't match any known combination — usually a typo.
Fix: Double-check spelling and casing against the operation tables on each resource page (all operation names are lower-kebab-case, e.g. send-text, not sendText).