Waarom een WhatsApp-bericht mislukte: de status failed en de fouten lezen
Een webhook met failed status betekent dat Meta een bericht dat het bedrijf via de API verstuurde niet kon verzenden of afleveren. Het komt aan op het veld messages met status failed en een errors-array met code, title, message, error_data.details en href. De code geeft de reden: 131047 venster gesloten, 131026 niet afleverbaar, 131049 marketinglimiet, 131050 marketing gestopt, 131042 betalingsprobleem.
easyCoexistence koppelt het nummer van je WhatsApp Business-app aan de Cloud API van Meta via Coexistence en stuurt failed statuses door naar je server, rechtstreeks of als getekende forwards wanneer automatiseringen aanstaan.
Er zijn meer dan 24 uur verstreken sinds de ontvanger voor het laatst reageerde; de oplossing van Meta is in plaats daarvan een template sturen.
Niet afgeleverd om de betrokkenheid in het ecosysteem gezond te houden; wacht minimaal 24 uur voordat je het marketingtemplate opnieuw verstuurt.
De ontvanger heeft ervoor gekozen om marketingberichten van het bedrijf te stoppen; Meta zegt dat je niet opnieuw moet proberen.
Een failed status bevat geen contacts-array, dus koppel de fout via statuses.id.
Wat Meta rekent: berichten worden gefactureerd bij aflevering, niet bij verzending.
Hoe ziet een failed status eruit?
Zoals elke status, plus errors. De contacts-array ontbreekt, recipient_user_id wordt weggelaten als het bericht naar een telefoonnummer is verzonden, en er is geen pricing-object. title en message bevatten dezelfde tekst, error_data.details legt het uit in één zin, en href verwijst naar de foutcodelijst van Meta. Dit is het voorbeeld van Meta zelf, een marketingtemplate dat is gestopt door de limiet per gebruiker:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"statuses": [
{
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI0QUQ2MjA4NEYyRkExNjMyREUA",
"status": "failed",
"timestamp": "1751142888",
"recipient_id": "16505551234",
"errors": [
{
"code": 131049,
"title": "This message was not delivered to maintain healthy ecosystem engagement.",
"message": "This message was not delivered to maintain healthy ecosystem engagement.",
"error_data": {
"details": "In order to maintain a healthy ecosystem engagement, the message failed to be delivered."
},
"href": "/documentation/business-messaging/whatsapp/support/error-codes"
}
]
}
]
},
"field": "messages"
}
]
}
]
}Welke foutcodes komen het vaakst terug, en wat betekenen ze?
Meta geeft fouten terug in het verzendantwoord, in een failed status, of in beide, dus dezelfde code kan je langs beide wegen bereiken, en je handler moet op beide plekken lezen. Dit zijn de codes die de meeste berichten verklaren die nooit aankomen, met de reden van Meta en het eerste dat je moet proberen. De volledige lijst staat in de foutcodereferentie van Meta:
Hoe moet een handler op elk soort fout reageren?
Sorteer de code op wat je daarna doet, voordat er iets opnieuw wordt geprobeerd. Een algemene nieuwe poging maakt van een marketing-opt-out herhaalde fouten en kan een blokkade verlengen, terwijl het negeren van een tijdelijke fout een bericht verliest dat een minuut later wel was aangekomen.
- Opnieuw proberen met backoff: 131000 onbekend, 131016 service niet beschikbaar, 130429 doorvoerlimiet bereikt.
- Eerst wachten: 131049, minstens 24 uur, want vroege pogingen kunnen die gebruiker tot 24 uur extra blokkeren.
- Het bericht wisselen: 131047 vereist een goedgekeurd template, omdat het venster van 24 uur gesloten is.
- Stoppen voor deze klant: 131050, tot een resume van
user_preferencesbinnenkomt. - Het account of de inhoud repareren: 131042 betaling, 131031 account beperkt, 131053 media.
Welke fouten verschijnen alleen als failed status?
Die waarvan Meta besluit nadat het verzoek is geaccepteerd. Het verzenden geeft een wamid terug, en de weigering komt later via deze webhook. Meta levert marketingtemplates niet af aan WhatsApp-gebruikers met Amerikaanse telefoonnummers (+1 met een Amerikaans netnummer). Een marketingtemplate aan een klant die marketingberichten heeft gestopt wordt verwerkt en daarna gemeld als mislukt met 131050, en de limiet per gebruiker voor marketing meldt 131049 op dezelfde manier.
Als het nummer geen webhook-bestemming heeft, komen deze fouten nergens zichtbaar terecht en lijkt het bericht gewoon verstuurd. Voor de volledige volgorde van controles wanneer een klant niets kreeg, zie de pagina over WhatsApp API-berichten die niet aankomen.
Wat verandert er bij een Coexistence-nummer?
Twee dingen tellen. Ten eerste geldt het venster van 24 uur alleen voor de API. De Coexistence-gids van Meta zegt dat berichten die vanuit de WhatsApp Business-app worden verstuurd niet onder het klantenservicevenster vallen. Na een 131047 kan de eigenaar die klant dus nog vanaf de telefoon antwoorden, terwijl jouw systeem een goedgekeurd template verstuurt.
Ten tweede is de doorvoer vast. Een nummer dat tegelijk in de app en de API wordt gebruikt, verstuurt maximaal 20 berichten per seconde, en wanneer je dat overschrijdt, krijg je 130429 terug. Al het andere leest hetzelfde als op elk Cloud API-nummer: hetzelfde veld, dezelfde errors-array, dezelfde codes.
Hoe zien automatiseringen en je AI een fout?
Dat hangt af van het moment waarop Meta nee zegt. Een weigering bij het verzenden, zoals 131047, laat de stap van de automatisering mislukken: de run toont Failed met het bericht van Meta in het tabblad Runs, en de eigenaar krijgt een e-mail zodat hij die klant zelf kan antwoorden. Automatiseringen controleren ook het venster voordat ze een vrij antwoord sturen, en slaan dan over met window_closed in plaats van het te proberen.
Een fout die Meta achteraf meldt, komt als failed status binnen op je Forward URL of directe bestemming, en de run blijft zoals die was. Een AI die een template via de MCP-connector heeft verstuurd, ziet de wamid en "sent: true". Vraag je systeem om de status van die wamid, of laat de assistent get_number_health uitvoeren wanneer veel berichten tegelijk mislukken.
Veelgemaakte fouten
- 131050 in een lus opnieuw proberen. De klant heeft marketingberichten gestopt, dus elke poging mislukt op dezelfde manier totdat de klant ze weer aanzet.
- Een 131049-marketingtemplate binnen enkele uren opnieuw versturen. Meta vraagt om minstens 24 uur, en vroege pogingen kunnen die gebruiker tot 24 uur extra blokkeren.
- Alleen de title loggen. error_data.details bevat de specifieke reden, dus sla code en details samen met de wamid op.
- Draaien zonder webhook-bestemming en de aflevering beoordelen aan de hand van het verzendantwoord, dat alleen zegt dat Meta het bericht heeft geaccepteerd.
Wanneer een antwoord van een automatisering bij het verzenden wordt geweigerd, toont de run de fout van Meta en krijg je een e-mail. Elk nummer wordt 24/7 bewaakt op verbroken verbindingen en kwaliteitsdalingen. Van US$ 9 tot US$ 0,75 per nummer per maand, dalend naarmate je nummers toevoegt, met de eerste 3 dagen gratis.
Veelgestelde vragen
Rekent Meta een mislukt bericht?
De prijspagina's van Meta zeggen dat er wordt gerekend voor berichten die worden afgeleverd, niet voor berichten die alleen worden verzonden. Een failed status bevat geen pricing-object. De kosten gaan naar het eigen WhatsApp Business Account van het bedrijf, en easyCoexistence rekent er nooit een toeslag op.
Betekent 131026 dat de klant het bedrijf heeft geblokkeerd?
De lijst van Meta voor 131026 noemt andere redenen: het nummer staat niet op WhatsApp, de ontvanger heeft de laatste voorwaarden niet geaccepteerd, of zijn WhatsApp-versie is te oud. Meta raadt aan de klant via een ander kanaal te vragen die punten na te gaan.
Waarom verschijnt recipient_user_id bij sommige fouten wel en bij andere niet?
Meta laat het weg bij een failed status wanneer het bericht naar een telefoonnummer is verzonden. Als je naar de BSUID van de klant hebt gestuurd, bevat de fout het wel, en dan kan recipient_id juist ontbreken.
Kan een bericht mislukken nadat het is afgeleverd?
De referentie van Meta beschrijft failed als een mislukte verzending of aflevering. Zodra een bericht het toestel heeft bereikt, zijn de volgende statussen die je kunt verwachten read, of played bij spraakberichten.
Lees verder
Klaar om te beginnen?
Stel WhatsApp Coexistence in enkele minuten in, niet maanden. De app blijft op je telefoon werken.
Start je gratis proefperiodeGeverifieerd op