Fehler der API v2

Jeder Fehler der API v2 kommt mit einem echten HTTP-Statuscode und derselben JSON-Struktur. Diese Seite listet jeden code auf, was er bedeutet und was zu tun ist. Jede Fehlerantwort verlinkt in docs auf ihren Code auf dieser Seite.

Das Fehlerobjekt#

{
  "error": {
    "code": "not_cancellable",
    "message": "Only a waiting message can be cancelled.",
    "field": null,
    "docs": "https://wbiztool.com/docs/api/v2/errors/#not_cancellable",
    "request_id": "req_4f1c2a9b8e7d6c5b4a392817",
    "status": "sent"
  }
}

Manche Codes fügen eigene Details hinzu, etwa status, count, used oder limit; sie stehen beim jeweiligen Code. Eine Antwort mit HTTP 401 hat außerdem einen Header WWW-Authenticate: Bearer realm="wbiztool", und Antworten mit 429 (sowie der 409 idempotency_in_progress) haben Retry-After.

Kurz gesagt: 4xx bedeutet, dass der Request geändert werden muss (oder, bei 409 und 429, dass Sie warten müssen); ihn unverändert zu wiederholen, ergibt dieselbe Antwort. 5xx bedeutet, dass das Problem bei uns liegt; wiederholen Sie den Request später mit demselben Idempotency-Key.

Authentifizierung und Limits#

api_v2_not_enabled#

HTTP 403. API v2 ist für diesen Arbeitsbereich nicht verfügbar. Wenn Sie das sehen, kontaktieren Sie uns.

Was zu tun ist: Nutzen Sie vorerst weiter API v1. Die Karte API-v2-Schlüssel unter Einstellungen → API-Schlüssel zeigt, wann sie für Sie freigeschaltet ist.

missing_api_key#

HTTP 401. Der Request hat keinen Header Authorization: Bearer …, oder er ist leer oder nutzt ein anderes Schema.

Was zu tun ist: Senden Sie bei jedem Request Authorization: Bearer wbz_live_… (oder wbz_test_…). Siehe Schlüssel.

invalid_api_key#

HTTP 401. Der Schlüssel ist kein v2-Schlüssel von WbizTool: falsch eingegeben, abgeschnitten oder nicht von uns erstellt.

Was zu tun ist: Kopieren Sie den Schlüssel erneut, ohne Leerzeichen oder Anführungszeichen. Ein Schlüssel kann nach dem Erstellen nicht noch einmal angezeigt werden; wenn Sie ihn verloren haben, erstellen Sie unter Einstellungen → API-Schlüssel einen neuen.

v1_key_on_v2#

HTTP 401. Der Schlüssel ist ein API-v1-Schlüssel (40 Zeichen, Ziffern und a bis f). v1-Schlüssel funktionieren nur unter /api/v1/.

Was zu tun ist: Erstellen Sie einen v2-Schlüssel in der Karte API-v2-Schlüssel unter Einstellungen → API-Schlüssel, oder rufen Sie API v1 auf.

api_key_revoked#

HTTP 401. Der Schlüssel wurde unter Einstellungen → API-Schlüssel widerrufen, oder sein Arbeitsbereich wurde gelöscht oder deaktiviert.

Was zu tun ist: Verwenden Sie einen anderen Schlüssel, oder bitten Sie einen Inhaber des Arbeitsbereichs, einen neuen zu erstellen.

api_key_expired#

HTTP 401. Das Ablaufdatum des Schlüssels ist überschritten.

Was zu tun ist: Bitten Sie einen Inhaber des Arbeitsbereichs, einen neuen Schlüssel zu erstellen, und ersetzen Sie den alten in Ihrer App.

too_many_auth_failures#

HTTP 429. Mehr als 30 Requests innerhalb einer Minute von Ihrer IP-Adresse hatten einen falschen Schlüssel. Retry-After ist 60.

Was zu tun ist: Halten Sie an und korrigieren Sie den Schlüssel in Ihrer App, dann versuchen Sie es nach einer Minute erneut.

demo_account#

HTTP 403. Ein Demo-Arbeitsbereich kann die API nicht nutzen.

Was zu tun ist: Registrieren Sie sich für ein eigenes Konto und erstellen Sie dort einen Schlüssel.

missing_scope#

HTTP 403. Dem Schlüssel fehlt der Scope, den dieser Request braucht. required_scope im Fehler nennt ihn, zum Beispiel messages:send.

Was zu tun ist: Erstellen Sie einen Schlüssel mit diesem Scope (einem vorhandenen Schlüssel lassen sich keine Scopes hinzufügen). Siehe Scopes.

rate_limited#

HTTP 429. Der Schlüssel hat in dieser Minute mehr als 60 Requests gestellt oder heute (UTC) mehr als 10.000.

Was zu tun ist: Warten Sie die Anzahl Sekunden in Retry-After ab und versuchen Sie es dann erneut. Verteilen Sie Requests zeitlich, nutzen Sie POST /messages/batch für viele Empfänger und Webhooks statt Polling. Siehe Rate-Limits.

Request#

not_found#

HTTP 404. Unter dieser Adresse gibt es nichts: Der Pfad ist falsch geschrieben oder kein Pfad der API v2.

Was zu tun ist: Vergleichen Sie den Pfad mit der Referenz, zum Beispiel /api/v2/messages, nicht /api/v2/message.

invalid_json#

HTTP 400. Der Body ist kein gültiges JSON, oft wegen eines abschließenden Kommas oder eines nicht maskierten Zeilenumbruchs in text.

Was zu tun ist: Prüfen Sie das JSON und schreiben Sie Zeilenumbrüche in Strings als \n. Lassen Sie Ihre HTTP-Bibliothek den Body erzeugen (json= in Python requests, JSON.stringify in JavaScript).

unsupported_content_type#

HTTP 415. Der Body wird nicht so gesendet, wie dieser Endpoint ihn annimmt: Jeder Endpoint nimmt application/json an, außer POST /media, der multipart/form-data annimmt.

Was zu tun ist: Setzen Sie Content-Type: application/json und senden Sie JSON, oder senden Sie den Upload als Multipart mit dem Feld file.

method_not_allowed#

HTTP 405. Der Pfad existiert, aber nicht mit dieser Methode, zum Beispiel PUT /messages/9817263.

Was zu tun ist: Verwenden Sie die Methode aus der Referenz. Eine Änderung an einer Erinnerung ist PATCH; das Stornieren einer Nachricht ist DELETE.

request_too_large#

HTTP 413. Der Body des Requests ist zu groß.

Was zu tun ist: Senden Sie weniger in einem Request, teilen Sie zum Beispiel eine lange Liste auf mehrere Batches auf.

validation_failed#

HTTP 400. Der Request hat nicht die richtige Struktur: Ein Pflichtfeld fehlt, ein Wert hat den falschen Typ oder ist zu lang, ein Feld ist unbekannt, oder limit liegt nicht zwischen 1 und 100. field nennt das erste Problem und message erklärt es; errors listet weitere auf.

Was zu tun ist: Korrigieren Sie das in field genannte Feld. Feldnamen sind snake_case, und unbekannte Felder werden abgelehnt. Prüfen Sie also auf Tippfehler wie txt oder phone_number.

invalid_cursor#

HTTP 400. Der cursor ist beschädigt oder wurde für andere Filter erstellt, als dieser Request hat.

Was zu tun ist: Senden Sie genau den erhaltenen next_cursor, mit denselben Filtern wie bei der ersten Seite. Um die Filter zu ändern, beginnen Sie neu ohne Cursor.

invalid_idempotency_key#

HTTP 400. Der Header Idempotency-Key ist leer, länger als 255 Zeichen oder enthält nicht druckbare Zeichen.

Was zu tun ist: Verwenden Sie eine UUID oder einen anderen kurzen String aus Buchstaben, Ziffern und Bindestrichen.

idempotency_key_reused#

HTTP 422. Dieser Idempotency-Key wurde in den letzten 24 Stunden bereits für einen anderen Request verwendet: eine andere Methode, einen anderen Pfad oder einen anderen Body.

Was zu tun ist: Verwenden Sie für jeden neuen Request einen neuen Key und verwenden Sie einen Key nur erneut, um genau denselben Request zu wiederholen. Siehe Idempotency-Key.

idempotency_in_progress#

HTTP 409. Der erste Request mit diesem Idempotency-Key wird noch bearbeitet. Retry-After ist 1.

Was zu tun ist: Warten Sie eine Sekunde und senden Sie denselben Request erneut: Sie erhalten die Antwort des ersten Requests.

internal_error#

HTTP 500. Bei uns ist etwas schiefgelaufen. Wir werden darüber informiert.

Was zu tun ist: Wiederholen Sie den Request später mit demselben Idempotency-Key, damit nichts doppelt ausgeführt wird. Wenn es immer wieder passiert, kontaktieren Sie uns mit der request_id.

Nachrichten#

text_required#

HTTP 400. Die Nachricht hat weder text noch media, oder der Text besteht nur aus Leerzeichen. Bei einer Erinnerung ist text erforderlich.

Was zu tun ist: Senden Sie text, media oder beides.

text_too_long#

HTTP 400. text ist länger als 3.000 Zeichen.

Was zu tun ist: Kürzen Sie ihn oder teilen Sie ihn auf mehrere Nachrichten auf.

too_many_recipients#

HTTP 400. Ein Batch hat mehr als 1.000 Empfänger in to.

Was zu tun ist: Teilen Sie die Liste in Batches mit bis zu 1.000 Empfängern auf, jeder mit eigenem Idempotency-Key.

invalid_datetime#

HTTP 400. Eine Zeitangabe (send_at, expires_at, since, until) ist nicht ISO 8601 mit Offset.

Was zu tun ist: Schreiben Sie sie wie 2026-10-20T09:30:00+05:30 oder 2026-10-20T04:00:00Z. Eine Zeit ohne Offset wie 2026-10-20 09:30 wird abgelehnt, weil sie mehrdeutig ist. In einem Query-String schreiben Sie + als %2B.

invalid_phone#

HTTP 422. Eine Telefonnummer (to.phone oder phone beim Verbinden einer Nummer) ist keine gültige Nummer im internationalen Format mit +.

Was zu tun ist: Schreiben Sie sie mit + und Ländervorwahl, zum Beispiel +919876543210. Leerzeichen und Bindestriche sind in Ordnung; eine führende 0 statt der Ländervorwahl nicht.

invalid_username#

HTTP 422. to.username ist kein Telegram-Benutzername.

Was zu tun ist: Schreiben Sie @name, einen Link t.me/name oder tg: mit einer Benutzer-ID. Siehe Empfänger.

username_needs_telegram#

HTTP 422. An einen Telegram-Benutzernamen kann nur von einem Telegram-Konto aus gesendet werden, und from ist eine WhatsApp-Nummer (oder, ohne from, ist nicht genau ein Telegram-Konto verbunden).

Was zu tun ist: Setzen Sie from auf die ID eines Telegram-Kontos, oder senden Sie stattdessen an eine Telefonnummer.

contact_not_found#

HTTP 422. Im Arbeitsbereich gibt es keinen Kontakt mit dieser to.contact_id.

Was zu tun ist: Prüfen Sie die ID (zum Beispiel die contact_id einer früheren Nachricht), oder senden Sie stattdessen an to.phone.

media_not_found#

HTTP 422 beim Senden einer Nachricht oder Erstellen einer Erinnerung mit media.media_id; HTTP 404 bei GET oder DELETE /media/{id}. Im Medienverzeichnis des Arbeitsbereichs gibt es keine Datei mit dieser ID, oder sie wurde gelöscht.

Was zu tun ist: Prüfen Sie die ID mit Dateien auflisten, oder laden Sie die Datei erneut hoch.

invalid_media_url#

HTTP 422. media.url ist kein öffentlicher http- oder https-Link: Er ist fehlerhaft oder zeigt auf eine private oder lokale Adresse.

Was zu tun ist: Verwenden Sie einen Link, den jeder im Internet öffnen kann, oder laden Sie die Datei hoch und senden Sie sie per media_id.

time_in_past#

HTTP 422. send_at oder expires_at liegt bereits in der Vergangenheit.

Was zu tun ist: Prüfen Sie die Zeit und ihren Offset. Um sofort zu senden, lassen Sie send_at weg.

number_not_found#

HTTP 422, wenn from (oder number_id beim Verbinden) keine Nummer dieses Arbeitsbereichs ist; HTTP 404 bei GET /numbers/{id}, auch wenn der Schlüssel diese Nummer nicht nutzen darf.

Was zu tun ist: Holen Sie die richtige id über Nummern auflisten.

from_required#

HTTP 422. from fehlt, und der Arbeitsbereich hat keine oder mehr als eine verbundene Nummer, sodass unklar ist, welche senden soll. (Bei einem Schlüssel, der auf einige Nummern beschränkt ist: Die einzige verbundene Nummer gehört nicht zu seinen Nummern.)

Was zu tun ist: Senden Sie from mit der id der Nummer, von der gesendet werden soll.

number_not_allowed#

HTTP 403. Der Schlüssel ist auf einige Nummern beschränkt, und dieser Request braucht eine andere: from ist eine andere Nummer, eine Erinnerung nennt keine seiner Nummern, ein Verbindungs-Request fügt eine Nummer hinzu oder nennt eine andere, oder der Request verwaltet Webhook-Endpunkte.

Was zu tun ist: Verwenden Sie eine der Nummern des Schlüssels (number_ids in GET /me) oder einen Schlüssel ohne Beschränkung.

no_credits#

HTTP 402. Der Arbeitsbereich hat in seinem Plan keine Nachrichten mehr übrig. Bei einem Batch geben requested und remaining an, wie viele angefordert wurden und wie viele übrig sind.

Was zu tun ist: Senden Sie weniger Nachrichten, oder kaufen Sie einen Plan oder weitere Nachrichten; kostenpflichtige Pläne senden unbegrenzt Nachrichten. Siehe Wenn Ihnen die Nachrichten ausgehen.

account_disabled#

HTTP 403. Das Konto des Inhabers des Arbeitsbereichs ist deaktiviert, daher kann der Arbeitsbereich nicht senden.

Was zu tun ist: Kontaktieren Sie den Support.

number_daily_cap_reached#

HTTP 429. Die sendende Nummer hat in den letzten 24 Stunden 1.000 Nachrichten gesendet (Fair Use), oder ein Batch passt nicht mehr in das, was übrig ist: requested und room geben an, wie viele.

Was zu tun ist: Senden Sie den Rest später oder von einer anderen Nummer.

message_rejected#

HTTP 422. Die Nachricht konnte nicht in die Warteschlange gestellt werden; message nennt den Grund. Es wurde nichts gespeichert.

Was zu tun ist: Beheben Sie, was message beschreibt, und senden Sie erneut.

message_not_found#

HTTP 404. Keine Nachricht mit dieser ID für diesen Schlüssel: Sie existiert nicht, gehört zu einem anderen Arbeitsbereich oder wurde von einer Nummer gesendet, die der Schlüssel nicht nutzen darf. Ein Testschlüssel sieht nur seine eigenen Testnachrichten, und ein Live-Schlüssel sieht sie nie.

Was zu tun ist: Prüfen Sie die ID und ob Sie dieselbe Art von Schlüssel (live oder test) verwenden, mit der die Nachricht erstellt wurde.

not_cancellable#

HTTP 409. Nur eine wartende Nachricht (queued oder scheduled) kann storniert werden, und diese wartet nicht mehr. status im Fehler gibt an, in welchem Status sie jetzt ist, zum Beispiel sent oder cancelled.

Was zu tun ist: Es gibt nichts zu stornieren. Eine gesendete Nachricht kann nicht zurückgeholt werden.

Erinnerungen#

invalid_cron#

HTTP 400. schedule.cron ist kein fünfteiliger Cron-Ausdruck oder beschreibt einen Zeitpunkt, der nie eintritt (zum Beispiel den 31. Februar).

Was zu tun ist: Schreiben Sie Minute, Stunde, Tag des Monats, Monat und Wochentag, zum Beispiel 0 9 * * 1 für montags um 09:00. Siehe Zeitplan.

invalid_timezone#

HTTP 400. schedule.timezone ist kein IANA-Zeitzonenname.

Was zu tun ist: Verwenden Sie einen Namen wie Asia/Kolkata, Europe/London oder America/New_York, keine Abkürzung wie IST und keinen Offset wie +05:30. Siehe die Zeitzonen-Referenz.

number_not_connected#

HTTP 422. Das from der Erinnerung ist keine verbundene Nummer dieses Arbeitsbereichs.

Was zu tun ist: Verbinden Sie die Nummer zuerst, wählen Sie eine verbundene, oder lassen Sie from weg (null), damit irgendeine verbundene Nummer sie sendet.

reminder_not_found#

HTTP 404. Keine Erinnerung mit dieser ID: Sie existiert nicht, wurde gelöscht oder sendet von einer Nummer, die der Schlüssel nicht nutzen darf.

Was zu tun ist: Prüfen Sie die ID mit Erinnerungen auflisten.

Medien#

file_too_large#

HTTP 413. Die hochgeladene Datei ist größer als 64 MB.

Was zu tun ist: Komprimieren oder teilen Sie sie; verringern Sie bei einem Video die Auflösung.

unsupported_file_type#

HTTP 415. Der Dateityp kann nicht über WhatsApp gesendet werden. Der Typ wird aus der Endung am Ende des Dateinamens gelesen.

Was zu tun ist: Prüfen Sie die Typen, die Sie hochladen können, und behalten Sie die Endung im Namen (price-list.pdf, nicht price-list).

storage_full#

HTTP 422. Die Datei passt für den Plan nicht mehr in das Medienverzeichnis des Arbeitsbereichs. used und limit geben an, wie viel belegt und erlaubt ist, in Byte.

Was zu tun ist: Löschen Sie Dateien, die Sie nicht mehr brauchen, oder wechseln Sie zu einem Plan mit mehr Speicherplatz.

media_in_use#

HTTP 409. Die Datei kann noch nicht gelöscht werden: Etwas wird sie noch senden (eine wartende Nachricht, auch die einer Kampagne, eine aktive Erinnerung oder ein aktiver Google-Sheets-Trigger). count gibt an, wie viele.

Was zu tun ist: Stornieren oder ändern Sie diese zuerst, oder warten Sie, bis die wartenden Nachrichten gesendet wurden.

upload_failed#

HTTP 502. Die Datei konnte bei uns nicht gespeichert werden.

Was zu tun ist: Versuchen Sie es erneut, mit demselben Idempotency-Key.

Nummernprüfungen#

no_valid_numbers#

HTTP 422. Keiner der Einträge in numbers ist eine Telefonnummer. skipped gibt an, wie viele Einträge es waren.

Was zu tun ist: Senden Sie Nummern im internationalen Format mit +, eine pro Eintrag, zum Beispiel +919876543210.

too_many_numbers#

HTTP 422. Die Prüfung enthält mehr Nummern, als eine Prüfung haben darf: über 10.000 Einträge im Request oder mehr Nummern, als der Plan pro Prüfung erlaubt. count und limit geben an, wie viele.

Was zu tun ist: Teilen Sie die Liste auf mehrere Prüfungen auf. Siehe Plan-Limits.

number_check_quota_reached#

HTTP 422. Die Prüfung würde das Kontingent an Nummernprüfungen des Plans für diesen Abrechnungszeitraum überschreiten. requested, used und limit geben an, wie viele.

Was zu tun ist: Prüfen Sie weniger Nummern, warten Sie auf den nächsten Abrechnungszeitraum, oder wechseln Sie zu einem höheren Plan.

number_check_not_found#

HTTP 404. Im Arbeitsbereich gibt es keine Nummernprüfung mit dieser ID.

Was zu tun ist: Prüfen Sie die ID mit Prüfungen auflisten.

Nummern#

plan_required#

HTTP 403. Der Plan des Arbeitsbereichs enthält nicht, was dieser Request braucht: die QR-Code-API, um eine Nummer zu verbinden, Erinnerungen, um eine Erinnerung zu erstellen, zu ändern oder fortzusetzen, oder Nummernverifizierung, um eine Nummernprüfung zu starten.

Was zu tun ist: Ein Inhaber kann unter Preise upgraden. Das Lesen vorhandener Daten funktioniert in jedem Plan.

number_limit_reached#

HTTP 403. Der Plan hat keinen Platz für eine weitere Nummer.

Was zu tun ist: Verbinden Sie eine vorhandene Nummer mit number_id erneut, entfernen Sie eine Nummer, die Sie nicht mehr verwenden, oder wechseln Sie zu einem höheren Plan.

already_connected#

HTTP 409. Die Nummer ist bereits verbunden.

Was zu tun ist: Nichts: Sie können von ihr senden. Prüfen Sie es mit Nummer abrufen.

connect_in_progress#

HTTP 409. Diese Nummer wird gerade verbunden. number_id im Fehler gibt an, welche.

Was zu tun ist: Fragen Sie GET /numbers/{id} für diese Nummer regelmäßig ab, statt erneut anzufragen. Nach 10 Minuten ohne Scan können Sie erneut anfragen.

Webhooks#

invalid_webhook_url#

HTTP 422. url ist keine öffentliche https://-Adresse: Sie ist http://, fehlerhaft oder zeigt auf eine private oder lokale Adresse.

Was zu tun ist: Verwenden Sie eine https://-Adresse, unter der Ihr Server aus dem Internet antwortet. Zum Testen auf Ihrem Computer nutzen Sie einen Tunnel-Dienst, der Ihnen eine öffentliche https://-Adresse gibt.

webhook_limit_reached#

HTTP 403. Der Arbeitsbereich hat bereits 5 Webhook-Endpunkte.

Was zu tun ist: Entfernen Sie einen, den Sie nicht mehr verwenden. Ein Endpunkt kann jeden Ereignistyp erhalten.

webhook_not_found#

HTTP 404. Kein Webhook-Endpunkt mit dieser ID: Er existiert nicht oder wurde entfernt. Auch das Testen oder das Rotieren des Secrets eines gestoppten Endpunkts ergibt diese Antwort; beim Lesen zeigt er active: false.

Was zu tun ist: Prüfen Sie die ID mit Endpunkte auflisten. Wenn er gestoppt wurde, fügen Sie ihn erneut hinzu.

Testmodus#

test_mode_unsupported#

HTTP 403. Ein Testschlüssel (wbz_test_…) kann Testnachrichten senden, lesen und stornieren und den Rest des Arbeitsbereichs lesen, aber nichts anderes ändern: keine Nummer verbinden, keine Erinnerungen erstellen, ändern oder löschen, keine Medien hochladen oder löschen, keine Nummernprüfung starten und keine Webhook-Endpunkte verwalten. Auch der Filter status von GET /messages wird für Testschlüssel nicht unterstützt.

Was zu tun ist: Verwenden Sie für diese Requests einen Live-Schlüssel (wbz_live_…). Siehe Testmodus.