Fehler & Idempotenz
Verzweigen Sie nach dem Fehlercode, nicht nach dem Status. Und machen Sie jeden Wiederholungsversuch, der Geld kostet, sicher.
Nach dem Code verzweigen, nicht nach dem Status
Fehler kommen als { "error": "<code>" } zurück. Der Status allein reicht nicht
aus, um zu entscheiden, was zu tun ist – zwei 403 können gegensätzliche
Korrekturen erfordern.
| Status | Code | Was es bedeutet und was zu tun ist |
|---|---|---|
| 401 | invalid_key | Unbekannter oder widerrufener Schlüssel. Erstellen Sie einen neuen; ein erneuter Versuch hilft nie. |
| 403 | ip_not_allowed | Der Schlüssel hat eine IP-Allowlist, und diese Adresse steht nicht darauf. Der Schlüssel ist in Ordnung – fügen Sie die Adresse unter developers.wasync.app/keys hinzu. Rotieren Sie ihn nicht. |
| 403 | insufficient_scope | Den Zugangsdaten fehlt der Scope, den dieser Endpunkt benötigt. |
| 403 | forbidden_portal_kind | POST /connections auf einem Bitrix24-Portal. Verbindungen dort legt der Portal-Administrator an. |
| 400 | invalid_phone_number | phoneNumber darf nur aus Ziffern bestehen, ohne führendes +. |
| 400 | invalid_webhook | Die URL muss HTTPS verwenden und auf einem öffentlich erreichbaren Host liegen. |
| 402 | — | Die Lizenz der Verbindung ist abgelaufen. Siehe Lizenzen & Testphase. |
| 409 | already_connected | Die Sitzung ist aktiv; es gibt nichts zu koppeln. |
| 409 | not_supported_for_provider | Eine Operation nur für qr auf einer cloud_api-Nummer. Dauerhaft – nicht erneut versuchen. |
| 422 | recipient_not_on_whatsapp | WhatsApp konnte für den Empfänger kein Konto finden. Prüfen Sie, ob die Nummer im internationalen Format vorliegt (zuerst die Landesvorwahl, keine führende Null) und ob die Person WhatsApp nutzt. Für diese Nummer dauerhaft – nicht unverändert erneut versuchen. |
| 502 | send_failed | WhatsApp konnte aus einem Grund nicht zustellen, der nicht beim Empfänger liegt (Sitzung oder Provider). Versuchen Sie es nach kurzer Pause erneut; besteht das Problem weiter, prüfen Sie den Status der Verbindung. |
| 429 | warmup_limited | Stündliches Warm-up-Limit bei einer neuen qr-Nummer. Warten Sie einige Minuten. |
| 429 | rate_limited | Missbrauchsbegrenzung. Beachten Sie Retry-After, wenn vorhanden; halten Sie in jedem Fall eine Standard-Wartezeit ein. |
| 502 | pairing_code_unavailable | Ein normales Ergebnis, kein Ausfall – weichen Sie auf den QR-Code aus. |
Retry-After wird nicht bei jedem 409/429 garantiert. Machen Sie Ihre
Wartezeit daher nie davon abhängig.
Idempotenz bei POST /connections
Das Anlegen einer Verbindung richtet eine WhatsApp-Sitzung ein und belegt einen
kostenpflichtigen Platz. Ein Client, der in ein Timeout läuft und es erneut
versucht, würde sonst eine zweite Verbindung anlegen – und Sie würden
unbemerkt für zwei Plätze für einen Kunden zahlen. Der optionale Header
Idempotency-Key schließt diese Lücke. Er wird nur bei
POST /connections unterstützt; lassen Sie ihn weg, verhält sich alles wie
bisher.
Ein Schlüssel ist eine beliebige undurchsichtige Zeichenfolge mit bis zu 255 Zeichen. Er ist Ihrem Workspace zugeordnet (zwei Partner mit derselben Zeichenfolge kollidieren nie) und gilt 24 Stunden ab der ersten Anfrage, die ihn verwendet hat.
201 Created.200 OK plus der Response-Header Idempotency-Replayed: true. Der qr in dieser Antwort wird frisch abgerufen und ist nicht der bei der ersten Erstellung gespeicherte Code: Kopplungscodes wechseln etwa alle 20 Sekunden, ein wiedergegebener veralteter QR ließe sich schlicht nicht scannen. Werten Sie 200 als Erfolg, nicht als Fehler.400 { "error": "idempotency_key_reuse" }. Verglichen wird ein Hash des kanonischen Bodys; die Reihenfolge der JSON-Schlüssel spielt daher keine Rolle.409 { "error": "idempotency_in_progress" } mit Retry-After: 1. Beachten Sie den Header und versuchen Sie es mit demselben Schlüssel erneut.Ein Schlüssel mit mehr als 255 Zeichen wird mit
400 { "error": "idempotency_key_invalid" } abgelehnt – er wird nie gekürzt. Ein
leerer Header oder einer nur aus Leerzeichen gilt als nicht vorhanden. Die Form
des Response-Bodys bleibt in allen Fällen unverändert.
Erzeugen Sie einen Schlüssel pro Onboarding-Versuch eines Kunden
Eine frische UUID (crypto.randomUUID()), die unmittelbar vor dem Aufruf
erzeugt und nur von den Wiederholungen dieses Aufrufs verwendet wird.
Verwenden Sie keinen Schlüssel pro Prozess, pro API key, pro Tag oder eine
Konstante. Bei einem so groben Schlüssel erhält der zweite Kunde, den Sie
anlegen, die Verbindung des ersten Kunden zurück statt seiner eigenen.
Idempotenz beim Senden
POST /messages akzeptiert einen idempotencyKey im Body (nicht als
Header). Senden Sie immer einen mit – eine UUID pro logischem Versand.
- Versuchen Sie es bei jedem Fehler oder Timeout mit dem gleichen Schlüssel erneut. Ein neuer Schlüssel bedeutet eine zweite echte WhatsApp-Nachricht auf dem Telefon des Empfängers.
- Fragen Sie bei
409 in_progressmit demselben Schlüssel erneut ab: Beachten SieRetry-After, wenn vorhanden, andernfalls warten Sie etwa 5 s. - Ein langsamer Versand ist kein fehlgeschlagener Versand. Setzen Sie Ihr HTTP-Timeout auf mindestens 180 s.