WhatsApp-API-Fehler: 401, 400, 409, 413 und 429 erklärt
Die meisten Integrationen werden am Idealfall gebaut und getestet: gültige Nummer, verbundenes Gerät, kurze Textnachricht. Wenn dann zum ersten Mal in der Produktion etwas schiefgeht, ist die Fehlerantwort der einzige Hinweis, den du hast. Dieser Leitfaden zeigt, welche Fehler POST /v1/messages tatsächlich zurückgibt, was sie jeweils auslöst und wie dein Code darauf reagieren sollte.
401 — ungültiger oder fehlender API-Schlüssel
Die häufigste Ursache ist nicht ein falscher, sondern ein abgelaufener oder widerrufener Schlüssel — zum Beispiel nach einer Schlüsselrotation im Dashboard, wenn du vergessen hast, eine bereits ausgerollte Integration zu aktualisieren. Einen 401 solltest du niemals automatisch wiederholen: Ein erneuter Versuch mit demselben falschen Schlüssel verbrennt nur Requests. Logge ihn deutlich und alarmiere einen Menschen, denn meist bedeutet er, dass jeder Versand fehlschlägt, nicht nur einer.
400 invalid_recipient — falsch formatierte Telefonnummer
Das ist der mit Abstand häufigste Ablehnungsgrund bei neuen Konten. Die API erwartet das E.164-Format (+ gefolgt von Ländervorwahl und Nummer, ohne Leerzeichen und ohne führende Null nach der Ländervorwahl). Eine aus einer Tabelle oder einem Formularfeld eingefügte Nummer behält oft die lokale Schreibweise wie 0151 23456789 statt +4915123456789, und die API lehnt sie ab, bevor sie WhatsApp überhaupt erreicht. Wenn du viele davon siehst, validiere und normalisiere Nummern, bevor sie die API erreichen — den regulären Ausdruck und die Normalisierungsschritte findest du im ausführlichen Leitfaden zur Validierung von Telefonnummern.
409 — Sitzung nicht verbunden
Das bedeutet, dass das mit deinem Konto verknüpfte WhatsApp-Gerät gerade nicht aktiv ist: Es wurde am Telefon abgemeldet, hat die Verbindung verloren oder wurde nie gekoppelt. Wiederholungen helfen hier nicht — die Lösung ist, den QR-Code im Dashboard erneut zu scannen. Wenn du unbeaufsichtigt sendest (etwa mit einem nächtlichen Erinnerungsjob), achte auf das Webhook-Event session.disconnected, damit du eine unterbrochene Kopplung bemerkst, bevor dein nächster Stapel komplett scheitert, statt es an einem Haufen 409-Antworten zu erkennen. Den gesamten Lebenszyklus der Kopplung — einschließlich dessen, was eine Trennung auslöst und wie die erneute Kopplung funktioniert — beschreibt So funktioniert die WhatsApp-Kopplung bei TextMeFlow.
413 / 415 — Medien zu groß oder nicht unterstützt
TextMeFlow akzeptiert Medien bis zu 100 MB pro Datei. Ein 413 bedeutet, dass die Datei diese Grenze überschreitet; ein 415 bedeutet, dass der Dateityp oder MIME-Typ von WhatsApp für diesen Nachrichtentyp nicht unterstützt wird (zum Beispiel eine .docx-Datei, die als „Bild"-Nachricht gesendet wird). Komprimiere oder konvertiere vor dem Hochladen, statt es erneut zu versuchen — die Datei wird nicht von selbst kleiner. Details zu unterstützten Typen und zum Media-Endpunkt stehen in der Medien-Dokumentation.
429 — zwei verschiedene Bedeutungen
Ein 429 ist nicht immer dasselbe Problem. TextMeFlow gibt ihn aus zwei verschiedenen Gründen zurück, die sich am Feld reason oder error im Body unterscheiden lassen:
burst_exceeded/hourly_exceeded— du hast das Rate Limit pro Nummer erreicht (1 Nachricht/Sekunde, 60/Minute, 1.000/Stunde), das verhindert, dass deine Nummer wie eine Spam-Quelle aussieht. Das ist vorübergehend; warte kurz und versuche es erneut. Der Leitfaden zu den Rate Limits nennt alle Zahlen, und Rate Limits und Nachrichtenstatus behandeln enthält funktionierenden Retry-Code für Node und Python.quota_exceeded— du hast das monatliche Nachrichtenkontingent deines Tarifs aufgebraucht (Free umfasst 50 Nachrichten/Monat, bezahlte Tarife beginnen bei 5 €/Monat). Das löst sich nicht von selbst; Wiederholungen bringen nichts, bis du upgradest oder der Abrechnungszeitraum neu beginnt.
Beide als „einfach nochmal versuchen" zu behandeln, ist ein häufiger Fehler — der zweite Fall wird endlos wiederholt und gelingt nie.
Empfänger hat sich abgemeldet (STOP)
Hat ein Empfänger zuvor mit STOP geantwortet (oder mit dem Äquivalent in der Sprache deines Flows), blockiert die Anti-Spam-Pipeline von TextMeFlow alle weiteren Sendungen an diese Nummer — ganz gleich, was deine Integration anfordert. Das ist kein Bug, den man umgehen sollte, sondern vorgeschriebene Abmeldeverarbeitung, und das erneute Senden an eine abgemeldete Nummer ist zudem genau der Weg, auf dem Nummern von WhatsApp selbst markiert und gesperrt werden. Die vollständige Anti-Spam-Pipeline (Rate Limits, Risiko-Score, STOP-Behandlung, Ruhezeiten) ist in der Anti-Spam-Dokumentation beschrieben.
Fehlerbehandlung, die nichts verschlimmert
Ein kurzes Denkmodell für die Retry-Logik:
- Nie wiederholen: 401 (Authentifizierung), 400 (Validierung — die Anfrage selbst ist falsch), 415 (nicht unterstützter Typ), quota_exceeded.
- Mit Backoff wiederholen: 429 mit
burst_exceededoderhourly_exceededsowie 5xx-Serverfehler. - Ursache beheben, nicht wiederholen: 409-Sitzungsfehler (neu koppeln), 413 (Datei verkleinern).
Wenn du den rohen Fehler-Body loggst — nicht nur den Statuscode —, geht die Fehlersuche deutlich schneller, denn die Fehlerantworten von TextMeFlow enthalten neben dem HTTP-Status einen maschinenlesbaren Grund.
Möchtest du diese Antworten an einem echten Konto sehen, statt nur darüber zu lesen? Starte kostenlos und sende deine erste Nachricht in wenigen Minuten — der kostenlose Tarif enthält 50 Nachrichten, genug, um jeden der oben genannten Fehlerpfade zu testen.
Selbst WhatsApp-Nachrichten per API senden?
Für immer gratis bis 50 Nachrichten/Monat. QR scannen und in 5 Minuten die erste Nachricht senden.
Für immer gratis