WhatsApp-Cloud-API-Fehlercodes: Bedeutung und Lösung

Dieser Leitfaden richtet sich an Entwickler und Messaging-Operations-Teams, die fehlgeschlagene WhatsApp-Nachrichten sehen und schnell wissen müssen, ob sie die Anfrage korrigieren, warten, den Nachrichtentyp wechseln oder aufhören sollen. Jeder Code unten wurde mit Metas Referenz zu den Cloud-API-Fehlercodes abgeglichen; Codes und Formulierungen ändern sich, prüfen Sie daher vor dem Hartcodieren von Logik die aktuelle Seite.

Wo treten WhatsApp-Cloud-API-Fehler auf?

Fehler treten an zwei Stellen auf, und Sie müssen beide erfassen. Anfragefehler kommen sofort in der API-Antwort zurück; Zustellfehler treffen später in einem Status-Webhook ein.

• Synchrone Fehler. Die Sendeanfrage wird abgelehnt, und die Antwort enthält ein error-Objekt mit code, message, type und oft error_data.details. Typische Beispiele sind abgelaufene Tokens, fehlende Parameter und Vorlagenabweichungen.
• Asynchrone Fehler. Die Sendeanfrage gelingt und liefert eine Nachrichten-ID, doch ein späterer Webhook meldet status: failed mit einem errors-Array. Typische Beispiele sind geschlossene Kundenservice-Fenster, nicht zustellbare Empfänger und Marketinglimits.

Ein häufiger Fehler ist, nur die HTTP-Antwort zu protokollieren. Teams glauben dann, eine Kampagne sei erfolgreich gewesen, weil jede Anfrage eine Nachrichten-ID zurückgab, während Hunderte Nachrichten in Webhooks fehlschlugen. Wie die Status zusammenhängen, lesen Sie unter gesendet, zugestellt, gelesen und fehlgeschlagen erklärt.

Welche WhatsApp-Fehlercodes sind am häufigsten?

Die Tabelle listet die Codes auf, denen die meisten Teams begegnen, gruppiert danach, was als Nächstes zu tun ist. Die Beschreibungen geben Metas Referenz sinngemäß wieder.

Wie beheben Sie die Fehler, die die meisten Kampagnenausfälle verursachen?

In der Praxis verursachen wenige Codes die meisten Fehlschläge. Für jeden gibt es eine klare Entscheidungsregel.

131047: Das Kundenservice-Fenster ist geschlossen

Der Kunde hat zuletzt vor mehr als 24 Stunden geschrieben. Freitext, Medien und interaktive Nachrichten sind nur innerhalb des 24-Stunden-Kundenservice-Fensters erlaubt; außerhalb müssen Sie eine genehmigte Vorlage verwenden, siehe das 24-Stunden-Kundenservice-Fenster. Agenten stoßen darauf häufig, wenn sie auf einen alten Chat antworten. Zeigen Sie Agenten den Fensterstatus an und bieten Sie nach Ablauf eine Vorlagenauswahl an.

131026: Nachricht nicht zustellbar

Beginnen Sie mit der Nummernhygiene: internationales Format, korrekte Ländervorwahl, keine führende Null nach der Vorwahl. Akzeptieren Sie dann, dass manche Nummern schlicht nicht bei WhatsApp sind oder eine alte App-Version nutzen. Weichen Sie bei zeitkritischen Nachrichten wie OTPs auf SMS aus. Siehe WhatsApp vs. SMS vs. RCS.

131049 und 131050: Marketinglimits und Abmeldungen

Beide betreffen Marketingnachrichten. 131050 ist die ausdrückliche Entscheidung des Nutzers, kein Marketing mehr zu erhalten; schließen Sie diese Nutzer für Marketing aus und abonnieren Sie Metas Webhook für Nutzerpräferenzen. 131049 bedeutet, dass Meta die Zustellung zum Schutz des Nutzer-Engagements unterlassen hat; Meta rät, mindestens 24 Stunden zu warten, denn frühere Wiederholungen scheitern voraussichtlich erneut. Senken Sie die Frequenz und erhöhen Sie die Relevanz, statt erneut zu senden.

130429, 131048 und 131056: zu schnell oder zu viel gesendet

130429 betrifft den Durchsatz: Nachrichten in eine Warteschlange stellen und Backoff anwenden. 131056 gilt auf Paarebene: Sie schreiben einer Person zu oft. 131048 ist ein Qualitätssignal zur Absendernummer und erfordert eine Korrektur bei Inhalt und Zielgruppenansprache, keinen Wiederholungsversuch. Siehe Nachrichtenlimits und Qualitätsbewertung.

132000, 132001 und 132012: Vorlagenabweichungen

Dabei handelt es sich fast immer um Integrationsfehler. Vorlagenname, Sprachcode (zum Beispiel ar im Unterschied zu en_US) und Anzahl der Variablen müssen exakt dem genehmigten Stand entsprechen. Bauen Sie einen Test, der jede Vorlage nach einer Änderung mit Beispielwerten sendet.

Eine Retry-Richtlinie, die Sie umsetzen können

Mit dieser Checkliste klassifizieren Sie jeden Fehlschlag automatisch.

1. Protokollieren Sie Code, Titel, error_data.details, Nachrichten-ID, Empfänger und Vorlagennamen.
2. Nie wiederholen bei 131050, 131021, 132016, 368 und 131031. Melden Sie 368 und 131031 sofort an einen Administrator.
3. Korrigieren, dann wiederholen bei Fehlern zu Autorisierung (0, 190, 10), Parametern (131008, 131009, 135000), Vorlagen (132000 bis 132015) und Abrechnung (131042). Alarmieren Sie das zuständige Team.
4. Mit Backoff wiederholen bei 130429, 4, 80007, 131016 und 131057, mit exponentiellem Backoff und Obergrenze.
5. Kanal oder Nachrichtentyp wechseln bei 131047 (Vorlage) und 131026 (SMS oder E-Mail).
6. 24 Stunden oder länger warten bei 131049 und die Kampagnenfrequenz überprüfen.
7. Berichten Sie Fehlschläge in Kampagnenberichten nach Code, nicht als einzelne Summe „fehlgeschlagen“.

Praxisbeispiel: Die fehlgeschlagene Aktion eines Händlers in Riad

Ein synthetisches Beispiel. „Najd Home“ sendet eine Marketing-Vorlage an 20.000 Kunden mit Einwilligung. Die API akzeptiert jede Anfrage, doch die Status-Webhooks zeigen rund 1.400 Fehlschläge.

Nach Codes gruppiert ist das Bild klar. Die größte Gruppe ist 131049, daher nimmt das Team diese Nutzer aus den nächsten beiden Sendungen heraus und senkt die wöchentliche Frequenz. Eine kleinere Gruppe ist 131026; die Analyse zeigt, dass viele Nummern mit lokaler führender Null gespeichert waren, was eine Normalisierung behebt. Mehrere Nutzer mit 131050 werden dauerhaft für Marketing ausgeschlossen. Einige 130429-Fehler stammten vom anfänglichen Ansturm, daher wird der Versand jetzt über eine Warteschlange getaktet.

Häufige Fehler und ehrliche Grenzen

• Jeden Fehlschlag als wiederholbar behandeln. Das verschwendet Budget und kann die Qualität senken.
• Metas Text hartcodieren. Meta aktualisiert Titel und Beschreibungen; richten Sie die Logik am numerischen Code aus und pflegen Sie eine Lookup-Tabelle, die Sie aktualisieren können.
• error_data.details ignorieren. Es nennt oft den genau fehlerhaften Parameter.
• Nicht jeder Fehlschlag hat eine Lösung. Manche Empfänger sind über WhatsApp nicht erreichbar, und Meta erklärt nicht jede 131049-Entscheidung. Planen Sie einen alternativen Kanal ein.

So unterstützt Sie OmniChannels.ai

OmniChannels.ai, die Plattform von BroadNet Technologies, stellt Teams Zustellberichte in Übersichts- und Detailansicht mit Filtern und CSV-Export bereit, sodass sich fehlgeschlagene Nachrichten pro Kampagne analysieren lassen. Schlägt WhatsApp fehl, kann der Kanal-Fallback die Nachricht erneut über RCS oder SMS senden. Vorlagen werden in einer Telefonvorschau geprüft und bis zur Genehmigung verfolgt, was Fehler durch nicht passende Vorlagen reduziert. Webhooks melden die Status FAILED und REJECTED in einem einheitlichen Format, und die öffentliche Entwicklerdokumentation enthält eine Referenz zu Fehlern und Limits.