Rate Limits und Nachrichtenstatus in der TextMeFlow API behandeln
Die meisten Integrationen, die WhatsApp-Nachrichten senden, laufen im Test einwandfrei und beginnen in der Produktion Nachrichten zu verlieren, sobald das Volumen steigt. Die Ursache ist meist kein kaputter API-Aufruf — sondern dass sich niemand um die 429-Antworten gekümmert hat. TextMeFlow begrenzt die Rate bewusst (warum, steht im Anti-Spam-Leitfaden), deine Integration muss das also erwarten und nicht als Fehler behandeln.
Dieser Leitfaden behandelt die zwei Dinge, die jede Produktionsintegration tun sollte: bei einem 429 korrekt zurückschalten und den Nachrichtenstatus abfragen, statt anzunehmen, ein 202 bedeute „zugestellt".
Warum du 429 siehst
Jeder Tarif hat eine Stundenobergrenze und ein Burst-Limit pro Minute — die aktuellen Zahlen stehen auf der Seite zu den Rate Limits. Zwei Situationen lösen bei POST /v1/messages ein 429 aus:
- Burst überschritten — zu viele Sendungen in der letzten Minute.
reason: burst_exceeded. - Stundenlimit überschritten — du hast die Stundenobergrenze des Tarifs erreicht.
reason: hourly_exceeded.
Beide Antworten enthalten im Body Retry-After-Semantik, sodass du genau weißt, wie lange du warten musst — kein Raten, kein fester Sleep.
Mit Backoff wiederholen, nicht mit festem Intervall
Eine naive Retry-Schleife (sleep(5); retry) verschwendet entweder Zeit oder bombardiert die API genau dann, wenn sie dir schon sagt, du sollst langsamer machen. Respektiere den Retry-Hinweis und füge zusätzlich exponentielles Backoff als Sicherheitspuffer hinzu.
Node.js:
async function sendMessage(to, text, attempt = 1) {
const res = await fetch('https://api.textmeflow.eu/v1/messages', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.TEXTMEFLOW_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ to, text }),
});
if (res.status === 429 && attempt <= 5) {
const body = await res.json();
const wait = (body.retry_after_seconds ?? 30) * attempt;
await new Promise((r) => setTimeout(r, wait * 1000));
return sendMessage(to, text, attempt + 1);
}
return res.json();
}
Python:
import time
import requests
def send_message(to, text, attempt=1):
res = requests.post(
"https://api.textmeflow.eu/v1/messages",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"to": to, "text": text},
)
if res.status_code == 429 and attempt <= 5:
wait = res.json().get("retry_after_seconds", 30) * attempt
time.sleep(wait)
return send_message(to, text, attempt + 1)
return res.json()
Begrenze die Versuche (fünf sind völlig ausreichend) und gib danach laut auf — eine Nachricht stillschweigend zu verlieren ist schlimmer, als einen Fehlschlag zu loggen, auf den dein Team reagieren kann.
202 bedeutet „in der Warteschlange", nicht „zugestellt"
POST /v1/messages gibt 202 Accepted mit einer message_id zurück, sobald die Nachricht in der Warteschlange liegt. Das ist, bevor sie überhaupt gesendet, geschweige denn gelesen wurde — die Pacing-Engine von TextMeFlow kann sie wegen der Ruhezeiten oder der im Anti-Spam-Leitfaden beschriebenen zufälligen Pacing-Verzögerung zurückhalten.
Braucht deine App das tatsächliche Ergebnis — für eine Buchungsbestätigung, einen Zahlungsbeleg, alles, worauf ein Mensch wartet —, dann frage GET /v1/messages/{id} mit der erhaltenen message_id ab:
async function waitForStatus(messageId, maxTries = 10) {
for (let i = 0; i < maxTries; i++) {
const res = await fetch(`https://api.textmeflow.eu/v1/messages/${messageId}`, {
headers: { Authorization: `Bearer ${process.env.TEXTMEFLOW_API_KEY}` },
});
const data = await res.json();
if (data.status === 'delivered' || data.status === 'failed') return data;
await new Promise((r) => setTimeout(r, 3000));
}
return null; // nach maxTries immer noch ausstehend — blockiere nicht endlos darauf
}
Für alles, was weniger zeitkritisch ist, musst du gar nicht abfragen — richte einen Webhook ein und lass TextMeFlow Statusänderungen an dich pushen. Abfragen eignet sich für die einmalige Prüfung „ist genau diese Nachricht angekommen"; Webhooks sind dafür da, alles im großen Stil zu verfolgen.
Kämpfe nicht mit urgent gegen den Pacer
POST /v1/messages akzeptiert ein Flag urgent: true, das die Ruhezeiten-Steuerung umgeht. Es existiert für den Fall des Türcodes um 23 Uhr, nicht als Abkürzung, um die Warteschlange aus Bequemlichkeit zu überspringen — jede erzwungene Sendung während der Ruhezeiten erhöht den Risk Score deines Kontos. Spare es dir für Nachrichten auf, auf die gerade aktiv ein Mensch wartet.
Alles zusammen
Ein belastbarer Sendeweg sieht so aus: mit Retry bei 429 senden, eine message_id zurückbekommen, diese bei zeitkritischen Flows abfragen oder deinen Webhook-Handler deine eigene Datenbank asynchron aktualisieren lassen und urgent für wirklich zeitkritische Nachrichten reservieren. Das ist der ganze Unterschied zwischen einer Integration, die unter Last stillschweigend Nachrichten verliert, und einer, die einfach funktioniert.
Starte mit dem kostenlosen Tarif — 50 Nachrichten/Monat, keine Kreditkarte — und baue die Retry-Logik ein, bevor du sie brauchst, nicht nach deinem ersten hektischen Samstag.
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