AnmeldenKostenlose Testphase starten
Meta Tech Provider

Warum eine WhatsApp-Nachricht fehlschlug: den Status failed und seine Fehler lesen

Ein Webhook für den failed-Status bedeutet, dass Meta eine Nachricht, die das Unternehmen über die API gesendet hat, nicht senden oder zustellen konnte. Er kommt im Feld messages mit status failed an und enthält ein errors-Array mit code, title, message, error_data.details und href. Der Code nennt den Grund: 131047 Zeitfenster geschlossen, 131026 nicht zustellbar, 131049 Marketing-Limit, 131050 Marketing beendet, 131042 Zahlungsproblem.

easyCoexistence verbindet Ihre Nummer aus der WhatsApp-Business-App über Coexistence mit der Cloud API von Meta und leitet failed-Status an Ihren Server weiter, direkt oder als signierte Weiterleitungen, wenn Automatisierungen aktiv sind.

131047

Seit der letzten Antwort des Empfängers sind mehr als 24 Stunden vergangen; Meta empfiehlt stattdessen, ein Template zu senden.

131049

Nicht zugestellt, um die Interaktion im Ökosystem gesund zu halten; warten Sie mindestens 24 Stunden, bevor Sie das Marketing-Template erneut senden.

131050

Der Empfänger hat Marketingnachrichten des Unternehmens abbestellt; Meta rät davon ab, es erneut zu versuchen.

No contacts

Ein failed-Status enthält kein contacts-Array; ordnen Sie den Fehler deshalb über statuses.id zu.

Delivered

Wofür Meta berechnet: Nachrichten werden bei Zustellung abgerechnet, nicht beim Senden.

Wie sieht ein failed-Status aus?

Wie jeder Status, aber mit errors. Das contacts-Array fehlt, recipient_user_id wird weggelassen, wenn die Nachricht an eine Telefonnummer gesendet wurde, und es gibt kein pricing-Objekt. title und message enthalten denselben Text, error_data.details erklärt ihn in einem Satz, und href verweist auf Metas Liste der Fehlercodes. Dies ist Metas eigenes Beispiel, ein Marketing-Template, das durch das Limit pro Nutzer gestoppt wurde:

Meta's example: a message that failed with 131049
{
  "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"
        }
      ]
    }
  ]
}

Welche Fehlercodes kommen am häufigsten vor, und was bedeuten sie?

Meta liefert Fehler in der Sendeantwort, in einem failed-Status oder in beiden, sodass derselbe Code auf beiden Wegen ankommen kann; Ihr Handler sollte beide Stellen auslesen. Hier sind die Codes, die die meisten nicht zugestellten Nachrichten erklären, mit Metas eigener Begründung und dem ersten Schritt zum Ausprobieren; die vollständige Liste steht in Metas Referenz der Fehlercodes:

131026Undeliverable: not a WhatsApp number, terms not accepted, or an outdated WhatsApp version on the recipient's phone.
131047More than 24 hours since the customer last wrote. Send an approved template instead.
131049Held back to keep engagement healthy, usually the per-user marketing limit. Wait 24 hours or more.
131050The customer stopped marketing messages from you. Do not retry.
131042A problem with the payment method on the WhatsApp Business Account.
130472Not sent because the recipient is part of Meta's marketing message experiment.
131053Media could not be uploaded, often an unsupported file type.
131000Unknown error. Try again; if it persists, open a Direct Support ticket.

Wie sollte ein Handler auf jede Art von Fehler reagieren?

Ordnen Sie den Code, bevor etwas erneut versucht wird, einer Folgeaktion zu. Ein pauschaler Wiederholungsversuch macht aus einer Marketing-Abmeldung wiederholte Fehlschläge und kann eine Sperre verlängern, während das Verwerfen eines temporären Fehlers eine Nachricht verliert, die eine Minute später zugestellt worden wäre.

  • Mit Backoff erneut versuchen: 131000 unbekannt, 131016 Dienst nicht verfügbar, 130429 Durchsatzgrenze erreicht.
  • Zuerst warten: 131049, mindestens 24 Stunden, da frühe Wiederholungen diesen Nutzer bis zu weitere 24 Stunden blockieren können.
  • Auf eine andere Nachricht umstellen: 131047 braucht ein genehmigtes Template, weil das 24-Stunden-Fenster geschlossen ist.
  • Für diesen Kunden stoppen: 131050, bis ein user_preferences-Resume eingeht.
  • Konto oder Inhalt korrigieren: 131042 Zahlung, 131031 Konto eingeschränkt, 131053 Medien.

Welche Fehler erscheinen nur als failed-Status?

Diejenigen, die Meta erst nach Annahme der Anfrage entscheidet. Das Senden liefert eine wamid zurück, und die Ablehnung kommt später über diesen Webhook. Meta liefert Marketing-Templates nicht an WhatsApp-Nutzer mit US-Telefonnummern (+1 mit US-Vorwahl). Ein Marketing-Template an einen Kunden, der Marketingnachrichten abbestellt hat, wird verarbeitet und danach mit 131050 als fehlgeschlagen gemeldet, und das Marketing-Limit pro Nutzer meldet 131049 auf dieselbe Weise.

Hat die Nummer kein Webhook-Ziel, landen diese Fehler nirgends, wo Sie sie sehen können, und die Nachricht wirkt einfach als gesendet. Die vollständige Prüfreihenfolge, wenn ein Kunde nichts erhalten hat, finden Sie auf der Seite zu nicht zugestellten WhatsApp-API-Nachrichten.

Was ändert sich bei einer Coexistence-Nummer?

Zwei Dinge sind wichtig. Erstens bindet das 24-Stunden-Fenster nur die API. Laut Metas Coexistence-Leitfaden unterliegen Nachrichten, die aus der WhatsApp-Business-App gesendet werden, nicht dem Kundenservice-Fenster. Nach einem 131047 kann der Inhaber diesen Kunden also weiterhin vom Telefon aus antworten, während Ihr System ein genehmigtes Template sendet.

Zweitens ist der Durchsatz festgelegt. Eine Nummer, die gleichzeitig in der App und in der API genutzt wird, sendet höchstens 20 Nachrichten pro Sekunde, und wer darüber hinausgeht, erhält 130429. Alles Übrige verhält sich wie bei jeder Cloud-API-Nummer: gleiches Feld, gleiches errors-Array, gleiche Codes.

Wie sehen Automatisierungen und Ihre KI einen Fehler?

Es hängt davon ab, wann Meta ablehnt. Eine Ablehnung zum Sendezeitpunkt, etwa 131047, lässt den Schritt der Automatisierung fehlschlagen: Der Lauf zeigt im Runs-Tab Failed mit der Meldung von Meta, und der Inhaber erhält eine E-Mail, damit er diesen Kunden selbst antworten kann. Automatisierungen prüfen außerdem das Zeitfenster, bevor sie eine Antwort im Freitext senden, und überspringen sie mit window_closed, statt es zu versuchen.

Ein Fehler, den Meta nachträglich meldet, kommt als failed-Status an Ihrer Forward URL oder dem direkten Ziel an, und der Lauf bleibt, wie er war. Eine KI, die über den MCP-Connector ein Template gesendet hat, sieht die wamid und "sent: true"; fragen Sie Ihr System nach dem Status dieser wamid oder lassen Sie den Assistenten get_number_health ausführen, wenn viele Nachrichten gleichzeitig fehlschlagen.

Häufige Fehler

  • 131050 in einer Schleife wiederholen. Der Kunde hat Marketingnachrichten abbestellt, daher scheitert jeder Versuch gleich, bis er sie wieder aktiviert.
  • Ein Marketing-Template mit 131049 innerhalb weniger Stunden erneut senden. Meta verlangt mindestens 24 Stunden, und frühe Wiederholungen können diesen Nutzer um bis zu weitere 24 Stunden blockieren.
  • Nur den title protokollieren. error_data.details enthält den konkreten Grund, deshalb speichern Sie Code und Details zusammen mit der wamid.
  • Ohne Webhook-Ziel arbeiten und die Zustellung allein an der Sendeantwort beurteilen, die nur bestätigt, dass Meta die Nachricht angenommen hat.
Mit EasyCoexistence

Lehnt Meta eine Antwort einer Automatisierung zum Sendezeitpunkt ab, zeigt der Lauf den Fehler von Meta, und Sie erhalten eine E-Mail. Jede Nummer wird rund um die Uhr auf Trennungen und Qualitätseinbußen überwacht. Von US$ 9 bis US$ 0.75 pro Nummer und Monat, sinkend mit jeder weiteren Nummer, mit den ersten 3 Tagen kostenlos.

Häufig gestellte Fragen

Stellt Meta eine fehlgeschlagene Nachricht in Rechnung?

Metas Preisseiten besagen, dass Nachrichten berechnet werden, die zugestellt wurden, nicht solche, die nur gesendet wurden. Ein failed-Status enthält kein pricing-Objekt. Die Kosten gehen an das eigene WhatsApp-Business-Konto des Unternehmens; easyCoexistence rechnet nie einen Aufschlag darauf.

Bedeutet 131026, dass der Kunde das Unternehmen blockiert hat?

Metas Liste zu 131026 nennt andere Gründe: Die Nummer ist nicht bei WhatsApp, der Empfänger hat die neuesten Bedingungen nicht akzeptiert oder seine WhatsApp-Version ist zu alt. Meta empfiehlt, diese Punkte über einen anderen Kanal beim Kunden zu klären.

Warum erscheint recipient_user_id bei manchen Fehlern und bei anderen nicht?

Meta lässt es bei einem failed-Status weg, wenn die Nachricht an eine Telefonnummer gesendet wurde. Wenn Sie an die BSUID des Kunden gesendet haben, ist es im Fehler enthalten, und dann fehlt möglicherweise recipient_id.

Kann eine Nachricht nach der Zustellung noch fehlschlagen?

Metas Referenz beschreibt failed als Fehler beim Senden oder Zustellen. Sobald eine Nachricht das Gerät erreicht hat, sind die nächsten erwartbaren Status read oder bei Sprachnachrichten played.

Weiterlesen

Bereit für den Start?

Richten Sie WhatsApp Coexistence in wenigen Minuten statt Monaten ein. Die App funktioniert weiterhin auf dem Telefon.

Kostenlose Testphase starten

Verifiziert am