22. Meta Error Reference
Two distinct sections, deliberately kept separate so this document never overstates what Shumoul's own code
actually does. Section 22.1 is grounded entirely in NotificationFailureClassifier's real source code —
these are the only error signatures this system currently recognizes and reacts to programmatically.
Section 22.2 is a general reference of additional Meta WhatsApp Cloud API platform error codes (drawn
from Meta's own public API documentation) that this system may encounter but does not currently classify
specially — they all fall through to the classifier's default Temporary bucket today.
22.1 Errors Actively Classified by This System
Source: Shumoul.Infrastructure/Services/Notifications/NotificationFailureClassifier.cs,
ClassifyWhatsApp method. This classifier inspects the .NET exception message string raised by a failed
send (a case-insensitive substring match), not a structured parse of Meta's JSON error object — so "matches"
below means "the exception message contained this substring," not "Meta returned exactly this code and
nothing else."
| Matched signature | Classified as | Retryable (per this classification) | System Action |
|---|---|---|---|
"429" | RateLimit | Yes — queued for retry via the Notification Framework's generic retry pipeline | Backs off and retries later; not surfaced as a permanent failure |
"131000" | InvalidRecipient | No | Recorded as failed; no automatic retry — the recipient itself is the problem, not a transient condition |
"131026" | InvalidRecipient | No | Same as above |
"token", "190", "200", or "401" | AuthenticationFailure | No (requires credential fix, not a retry) | Recorded as failed; should raise an operational alert, since it implies the platform's or tenant's access token needs attention |
"timeout" or "timed out" | Timeout | Yes | Queued for retry |
Exception type name contains IOException, SocketException, or HttpRequestException | NetworkFailure | Yes | Queued for retry |
Exception type name contains TaskCanceledException or OperationCanceledException | Timeout | Yes | Queued for retry |
| None of the above | Temporary (default) | Yes | Queued for retry — the safe default for anything unrecognized |
What These Codes Mean (Meta's Definitions) and Recommended UI Messages
| Code / Signature | Meaning (Meta) | User Action | Recommended UI Message |
|---|---|---|---|
131000 | Generic "message failed to send" — often a downstream Meta-side issue | None — wait and retry manually if the classifier doesn't auto-retry | "This message could not be delivered. Please try again in a few minutes." |
131026 | Message undeliverable — recipient's number is not reachable on WhatsApp, or has not opted in / is not in an allowed test-number list (sandbox apps) | Verify the recipient's number is correct and has WhatsApp installed | "This phone number cannot receive WhatsApp messages right now." |
190 | Access token expired or invalid | None (admin action required) | "WhatsApp connection needs attention. Please contact support." (never expose token details to end users) |
200 | Permission error — the token lacks the required permission/scope for this action | None (admin action required) | Same as above |
401 | Unauthorized — invalid or missing credentials | None (admin action required) | Same as above |
429 | Rate limit exceeded | None — system will retry automatically | "High message volume — this will be retried automatically." |
22.2 Additional Meta Platform Error Codes (Reference Only — Not Yet Classified by This System)
These are documented, publicly known Meta WhatsApp Cloud API error codes that this system has not coded
any special handling for — a message failing with one of these today falls into the classifier's default
Temporary bucket and is retried like any unrecognized transient error, which may not always be the
correct behavior (e.g. a permanently-invalid template will never succeed no matter how many times it is
retried). Listed here so a future phase has a starting point for expanding ClassifyWhatsApp, not because
this system currently does anything special with them.
| Code | Meaning | Retryable | Recommended System Action (if implemented) |
|---|---|---|---|
131047 | Re-engagement message — outside the 24-hour customer-service window; a template message is required instead of free text | No | Should be classified as a permanent failure prompting a template-based resend, not a blind retry |
131053 | Media upload error — the referenced media URL could not be fetched or is invalid | No | Should surface a "media URL unreachable" error distinct from a generic send failure |
132000 | Template parameter count mismatch | No | Should be classified as a permanent configuration error, not retried |
132001 | Template does not exist or is not approved for the specified language | No | Same — permanent, configuration-level |
132005 | Template is paused (quality rating dropped) | No | Permanent until template quality recovers on Meta's side |
133010 | Account not registered / not onboarded correctly on the Cloud API | No | Permanent — requires Meta Business Manager remediation |
368 | Business account temporarily or permanently restricted by Meta | No | Permanent — requires Meta-side account review |
80007 | Cloud API rate limit hit (distinct numeric code from the generic HTTP 429) | Yes | Should be treated the same as the "429" substring match already handled |
Recommendation for a future phase (not undertaken here per this phase's documentation-only scope):
expand ClassifyWhatsApp to parse the structured Meta error JSON (code/title/message/error_data)
directly from the webhook status payload (see §21.12)
rather than relying on substring-matching a .NET Exception.Message, which only covers synchronous send
failures and never sees the richer error detail available in an asynchronous webhook-delivered failure
status.