WhatsApp Cloud API: Durchsatz und Rate Limits erklärt

Welche Fehlercodes treten bei einem Limit auf?

Ordnen Sie den Code dem Limit zu und wählen Sie dann die Reaktion.

Die Codes 131048 und 131049 betreffen Qualität und Engagement statt Geschwindigkeit, schnelleres Wiederholen hilft also nicht. Siehe Fehlerbehebung bei WhatsApp-API-Fehlercodes.

In der API von OmniChannels.ai kommt eine Ablehnung durch den Upstream als HTTP 502 mit Metas Fehlercode und Text in message an, und unser eigenes Rate Limiting liefert 429 mit einem Retry-After-Header. Die vollständige Tabelle und die Standardlimits finden Sie unter Fehler und Limits.

Wie stelle ich in die Warteschlange und wiederhole?

Setzen Sie eine Warteschlange zwischen Ihre Anwendung und die API, begrenzen Sie die Rate unterhalb Ihrer Grenze und wiederholen Sie nur, was später gelingen kann.

1. Jeden Versand in die Warteschlange stellen. Ihre Anwendung schreibt Nachrichten in eine Warteschlange, und ein Worker-Pool arbeitet sie ab. Iterieren Sie nie in einem einzigen Request-Handler über eine Kundenliste.
2. Die Rate mit einem Token Bucket begrenzen, der unter Ihrem Durchsatz liegt und Platz für Antworten und anderen Traffic lässt, der sich dieselbe Grenze teilt.
3. Jeden Versuch zuerst erfassen. Schreiben Sie je Nachricht eine Zeile mit Ihrer eigenen Operations-ID, speichern Sie die zurückgegebene Nachrichten-ID und überspringen Sie alles, was bereits angenommen wurde.
4. Vorübergehende Fehler wiederholen. Drosselungen und temporäre Serverfehler werden wiederholt; Validierungsfehler (400), Authentifizierungsfehler und Vorlagenfehler nicht.
5. Backoff mit Jitter. Warten Sie nach jedem Versuch länger, fügen Sie Zufall hinzu, damit Worker nicht gleichzeitig wiederholen, und begrenzen Sie Wartezeit und Anzahl der Versuche.
6. Retry-After beachten, wenn die Antwort es enthält.
7. Nach einem Timeout vor dem erneuten Senden prüfen. Eine verlorene Antwort heißt nicht, dass die Nachricht verloren ging; sehen Sie zuerst in die Statusereignisse.

const RETRYABLE = new Set([429, 500, 502, 503, 504]);

async function sendWithBackoff(send, { maxAttempts = 5, baseMs = 500, capMs = 30000 } = {}) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const res = await send();
    if (res.ok) return res;
    if (!RETRYABLE.has(res.status) || attempt === maxAttempts) throw new Error(`failed: ${res.status}`);
    const wait = Math.random() * Math.min(capMs, baseMs * 2 ** (attempt - 1)); // full jitter
    await new Promise((r) => setTimeout(r, wait));
  }
}

Metas Durchsatz-Seite nennt keine Backoff-Regel für Fehler 130429, es handelt sich also um gängige Ingenieurspraxis. Behandeln Sie ein 502 mit einem Meta-Drosselungscode als wiederholbar; bei jedem anderen Upstream-Code lesen Sie zuerst die Meldung. Unsere Seite Fehler und Limits enthält die vollständige Wiederholungstabelle und den Schutz vor doppeltem Versand.

Wie plane ich einen großen Versand?

Ermitteln Sie Dauer, Limits und Webhook-Last, bevor Sie starten.

1. Eindeutige Empfänger zählen und mit Ihrem Nachrichtenlimit vergleichen. Beginnen Sie mit dem Plan zur sicheren Skalierung, wenn die Liste größer ist als Ihre Stufe.
2. Dauer schätzen. Nachrichten geteilt durch Ihren Durchsatz ergibt Sekunden. Rechnerisch brauchen 100.000 Nachrichten bei 80 pro Sekunde 1.250 Sekunden, etwa 21 Minuten, wenn nichts anderes die Grenze beansprucht.
3. Kapazität reservieren. Die Grenze zählt auch eingehende Nachrichten, lassen Sie also während des Versands Spielraum für Kundenantworten.
4. Webhook-Server dimensionieren. Laut Meta sollen Webhook-Server das Dreifache Ihres ausgehenden Nachrichten-Traffics plus Ihren erwarteten eingehenden Traffic bewältigen, bei einer Median-Latenz von höchstens 250 ms und unter 1 % der Anfragen über 1 Sekunde. Siehe den Webhook-Leitfaden.
5. Vorlagenzustand und Qualität zuerst prüfen und den Versand in Batches staffeln, damit Sie stoppen können, wenn Fehler oder Blockierungen zunehmen. Siehe Massenversand ohne Sperre.
6. Media-IDs nutzen statt Links, wenn Sie Dateien in größerem Volumen senden, wie Meta rät. Siehe Medientypen und Limits.

Bei OmniChannels.ai nehmen Bulk-Endpunkte viele Empfänger in einer Anfrage entgegen, und ein Feld delay kann die Zustellung drosseln. Stimmen Sie Spitzenpläne vorab mit unserem Team ab.

Praxisbeispiel: ein Flash-Sale in Dubai

„Marina Gadgets“ (fiktiv) plant eine Flash-Sale-Vorlage an 60.000 Kunden mit Opt-in.

1. Ihr Limit erlaubt es, das Volumen ist also nicht der Engpass, sondern die Geschwindigkeit. Bei 80 mps brauchen 60.000 Nachrichten 750 Sekunden.
2. Sie senden in sechs Batches zu je 10.000 mit einem Rate Limiter bei 60 mps, was Platz für Antworten lässt.
3. In einem Batch erscheinen mehrere 131056-Fehler bei Kunden, die in derselben Minute auch ein Bestell-Update erhielten. Diese Sendungen verzögern sie um einige Minuten.
4. Ein Worker wiederholt gedrosselte Anfragen mit Backoff und Jitter, und keine Nachricht wird wiederholt, sobald sie eine ID hat.
5. Der Webhook-Endpunkt speichert Ereignisse und gibt 200 zurück, danach aktualisiert ein Worker die Status.
6. Nach jedem Batch prüfen sie Fehler und Vorlagenqualität, bevor es weitergeht.

Welche typischen Fehler gibt es?

• Limits verwechseln. Durchsatz, Pair-, Graph-API- und Nachrichtenlimits sind unterschiedliche Probleme.
• Sofort wiederholen, wodurch die Nummer an der Grenze bleibt und das Problem verlängert wird.
• An der Grenze senden, sodass Antworten und Status mit der Kampagne konkurrieren.
• Nach einem Timeout erneut senden, ohne den Status zu prüfen, was Nachrichten dupliziert.
• Graph-API-Endpunkte in einer Schleife abfragen und das Stundenlimit erreichen.
• Zu klein dimensionierte Webhook-Server, die zurückfallen und Wiederholungen auslösen.
• Limits ändern sich. Dieser Leitfaden nennt Metas Werte zum Redaktionszeitpunkt.

So hilft OmniChannels.ai

BroadNet ist ein offizieller Meta Business Solution Provider, und OmniChannels.ai sendet WhatsApp über eine API mit Bulk-Endpunkten, einem Feld delay zur Drosselung, Planung und Zustellstatus in einem einheitlichen, normalisierten Webhook-Format. Reseller erhalten getrennte Webhooks und Guthaben je Unterkonto. Planen Sie Spitzen mit unserem Team, und lesen Sie die WhatsApp-API-Dokumentation, Fehler und Limits und die Seite Kampagnen.