Erreurs de l'API v2

Chaque erreur de l'API v2 arrive avec un vrai code de statut HTTP et la même forme JSON. Cette page liste chaque code, sa signification et la marche à suivre. Chaque réponse d'erreur renvoie vers son code sur cette page dans docs.

L'objet erreur#

{
  "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"
  }
}

Certains codes ajoutent leurs propres détails, comme status, count, used ou limit ; ils sont indiqués avec le code. Une réponse avec le code HTTP 401 a aussi un en-tête WWW-Authenticate: Bearer realm="wbiztool", et les réponses 429 (ainsi que le 409 idempotency_in_progress) ont Retry-After.

En bref : 4xx signifie que la requête doit être modifiée (ou, pour 409 et 429, qu'il faut attendre) ; la renvoyer telle quelle donne la même réponse. 5xx signifie un problème de notre côté ; réessayez plus tard, avec la même Idempotency-Key.

Authentification et limites#

api_v2_not_enabled#

HTTP 403. L'API v2 n'est pas disponible pour cet espace de travail. Si vous voyez cette erreur, contactez-nous.

Que faire : continuez d'utiliser l'API v1 pour l'instant. La carte Clés API v2 de Paramètres → Clés API indique quand elle vous est ouverte.

missing_api_key#

HTTP 401. La requête n'a pas d'en-tête Authorization: Bearer …, ou il est vide ou utilise un autre schéma.

Que faire : envoyez Authorization: Bearer wbz_live_… (ou wbz_test_…) sur chaque requête. Voir Clés.

invalid_api_key#

HTTP 401. La clé n'est pas une clé v2 de WbizTool : mal saisie, tronquée, ou pas créée par nous.

Que faire : copiez de nouveau la clé, sans espaces ni guillemets. Une clé ne peut pas être réaffichée une fois créée ; si vous l'avez perdue, créez-en une nouvelle sur Paramètres → Clés API.

v1_key_on_v2#

HTTP 401. La clé est une clé de l'API v1 (40 caractères, des chiffres et les lettres de a à f). Les clés v1 ne fonctionnent que sur /api/v1/.

Que faire : créez une clé v2 dans la carte Clés API v2 de Paramètres → Clés API, ou appelez l'API v1.

api_key_revoked#

HTTP 401. La clé a été révoquée sur Paramètres → Clés API, ou son espace de travail a été supprimé ou désactivé.

Que faire : utilisez une autre clé, ou demandez à un propriétaire de l'espace de travail d'en créer une nouvelle.

api_key_expired#

HTTP 401. La date d'expiration de la clé est passée.

Que faire : demandez à un propriétaire de l'espace de travail de créer une nouvelle clé, et remplacez l'ancienne dans votre application.

too_many_auth_failures#

HTTP 429. Plus de 30 requêtes en une minute depuis votre adresse IP avaient une clé incorrecte. Retry-After vaut 60.

Que faire : arrêtez-vous et corrigez la clé dans votre application, puis réessayez après une minute.

demo_account#

HTTP 403. Un espace de travail de démonstration ne peut pas utiliser l'API.

Que faire : inscrivez-vous pour obtenir votre propre compte et créez-y une clé.

missing_scope#

HTTP 403. La clé n'a pas le scope dont cette requête a besoin. required_scope dans l'erreur indique lequel, par exemple messages:send.

Que faire : créez une clé avec ce scope (on ne peut pas ajouter de scope à une clé existante). Voir Scopes.

rate_limited#

HTTP 429. La clé a fait plus de 60 requêtes cette minute, ou plus de 10 000 aujourd'hui (UTC).

Que faire : attendez le nombre de secondes indiqué dans Retry-After, puis réessayez. Étalez les requêtes, utilisez POST /messages/batch pour de nombreux destinataires, et les webhooks plutôt que des interrogations en boucle. Voir Limites de débit.

Requête#

not_found#

HTTP 404. Il n'y a rien à cette adresse : le chemin est mal saisi, ou n'est pas un chemin de l'API v2.

Que faire : comparez le chemin à la référence, par exemple /api/v2/messages, et non /api/v2/message.

invalid_json#

HTTP 400. Le corps n'est pas du JSON valide, souvent à cause d'une virgule finale ou d'un retour à la ligne non échappé dans text.

Que faire : vérifiez le JSON, et écrivez les retours à la ligne dans les chaînes sous la forme \n. Laissez votre bibliothèque HTTP construire le corps (json= avec Python requests, JSON.stringify en JavaScript).

unsupported_content_type#

HTTP 415. Le corps n'est pas envoyé de la façon dont cet endpoint l'accepte : chaque endpoint accepte application/json, sauf POST /media, qui accepte multipart/form-data.

Que faire : définissez Content-Type: application/json et envoyez du JSON, ou envoyez le téléversement en multipart avec le champ file.

method_not_allowed#

HTTP 405. Le chemin existe, mais pas avec cette méthode, par exemple PUT /messages/9817263.

Que faire : utilisez la méthode indiquée dans la référence. Une modification de rappel se fait avec PATCH ; l'annulation d'un message avec DELETE.

request_too_large#

HTTP 413. Le corps de la requête est trop volumineux.

Que faire : envoyez moins de données par requête, par exemple en découpant une longue liste en plusieurs lots.

validation_failed#

HTTP 400. La requête n'a pas la bonne forme : un champ obligatoire manque, une valeur a le mauvais type ou est trop longue, un champ est inconnu, ou limit n'est pas entre 1 et 100. field nomme le premier problème et message l'explique ; errors liste les autres.

Que faire : corrigez le champ indiqué dans field. Les noms de champs sont en snake_case et les champs inconnus sont refusés : vérifiez donc les fautes de frappe comme txt ou phone_number.

invalid_cursor#

HTTP 400. Le cursor est endommagé, ou a été créé pour d'autres filtres que ceux de cette requête.

Que faire : envoyez exactement le next_cursor reçu, avec les mêmes filtres que pour la première page. Pour changer de filtres, recommencez sans curseur.

invalid_idempotency_key#

HTTP 400. L'en-tête Idempotency-Key est vide, dépasse 255 caractères, ou contient des caractères non imprimables.

Que faire : utilisez un UUID ou une autre chaîne courte composée de lettres, de chiffres et de tirets.

idempotency_key_reused#

HTTP 422. Cette Idempotency-Key a déjà été utilisée au cours des dernières 24 heures avec une requête différente : une autre méthode, un autre chemin ou un autre corps.

Que faire : utilisez une nouvelle clé pour chaque nouvelle requête, et ne réutilisez une clé que pour retenter exactement la même requête. Voir Idempotency-Key.

idempotency_in_progress#

HTTP 409. La première requête avec cette Idempotency-Key est encore en traitement. Retry-After vaut 1.

Que faire : attendez une seconde et renvoyez la même requête : vous recevrez la réponse de la première requête.

internal_error#

HTTP 500. Un problème est survenu de notre côté. Nous en sommes avertis.

Que faire : réessayez plus tard avec la même Idempotency-Key, pour que le travail ne soit pas fait deux fois. Si cela se reproduit, contactez-nous avec le request_id.

Messages#

text_required#

HTTP 400. Le message n'a ni text ni media, ou le texte ne contient que des espaces. Pour un rappel, text est obligatoire.

Que faire : envoyez text, media ou les deux.

text_too_long#

HTTP 400. text dépasse 3 000 caractères.

Que faire : raccourcissez-le, ou découpez-le en plusieurs messages.

too_many_recipients#

HTTP 400. Un lot a plus de 1 000 destinataires dans to.

Que faire : découpez la liste en lots de 1 000 au maximum, chacun avec sa propre Idempotency-Key.

invalid_datetime#

HTTP 400. Une heure (send_at, expires_at, since, until) n'est pas au format ISO 8601 avec son décalage.

Que faire : écrivez-la comme 2026-10-20T09:30:00+05:30 ou 2026-10-20T04:00:00Z. Une heure sans décalage, comme 2026-10-20 09:30, est refusée car elle est ambiguë. Dans une chaîne de requête, écrivez + sous la forme %2B.

invalid_phone#

HTTP 422. Un numéro de téléphone (to.phone, ou phone lors de la connexion d'un numéro) n'est pas un numéro valide au format international avec +.

Que faire : écrivez-le avec + et l'indicatif du pays, comme +919876543210. Les espaces et les tirets sont acceptés ; un 0 initial à la place de l'indicatif du pays ne l'est pas.

invalid_username#

HTTP 422. to.username n'est pas un nom d'utilisateur Telegram.

Que faire : écrivez @name, un lien t.me/name ou tg: suivi d'un identifiant d'utilisateur. Voir Destinataires.

username_needs_telegram#

HTTP 422. On ne peut envoyer à un nom d'utilisateur Telegram que depuis un compte Telegram, et from est un numéro WhatsApp (ou, sans from, il n'y a pas exactement un compte Telegram connecté).

Que faire : définissez from sur l'identifiant d'un compte Telegram, ou envoyez plutôt à un numéro de téléphone.

contact_not_found#

HTTP 422. Aucun contact avec ce to.contact_id dans l'espace de travail.

Que faire : vérifiez l'identifiant (le contact_id d'un message précédent, par exemple), ou envoyez plutôt à to.phone.

media_not_found#

HTTP 422 lors de l'envoi d'un message ou de la création d'un rappel avec media.media_id ; HTTP 404 pour GET ou DELETE /media/{id}. Il n'y a aucun fichier avec cet identifiant dans le Répertoire média de l'espace de travail, ou il a été supprimé.

Que faire : vérifiez l'identifiant avec Lister les fichiers, ou téléversez de nouveau le fichier.

invalid_media_url#

HTTP 422. media.url n'est pas un lien http ou https public : il est mal formé, ou pointe vers une adresse privée ou locale.

Que faire : utilisez un lien que n'importe qui sur Internet peut ouvrir, ou téléversez le fichier et envoyez-le par media_id.

time_in_past#

HTTP 422. send_at ou expires_at est déjà passé.

Que faire : vérifiez l'heure et son décalage. Pour envoyer maintenant, omettez send_at.

number_not_found#

HTTP 422 lorsque from (ou number_id lors d'une connexion) n'est pas un numéro de cet espace de travail ; HTTP 404 pour GET /numbers/{id}, y compris lorsque la clé ne peut pas utiliser ce numéro.

Que faire : obtenez le bon id avec Lister les numéros.

from_required#

HTTP 422. from manque, et l'espace de travail n'a aucun numéro connecté ou en a plusieurs : on ne sait donc pas lequel doit envoyer. (Pour une clé limitée à certains numéros : le seul numéro connecté ne fait pas partie de ses numéros.)

Que faire : envoyez from avec l'id du numéro depuis lequel envoyer.

number_not_allowed#

HTTP 403. La clé est limitée à certains numéros, et cette requête en demande un autre : from est un autre numéro, un rappel n'indique pas l'un de ses numéros, une demande de connexion ajoute un numéro ou en désigne un autre, ou la requête gère des endpoints de webhook.

Que faire : utilisez l'un des numéros de la clé (number_ids dans GET /me), ou une clé qui n'est pas limitée.

no_credits#

HTTP 402. L'espace de travail n'a plus de messages sur son forfait. Pour un lot, requested et remaining indiquent combien de messages ont été demandés et combien il en reste.

Que faire : envoyez moins de messages, ou achetez un forfait ou des messages supplémentaires ; les forfaits payants envoient des messages illimités. Voir Quand il ne reste plus de messages.

account_disabled#

HTTP 403. Le compte du propriétaire de l'espace de travail est désactivé : l'espace de travail ne peut donc pas envoyer.

Que faire : contactez le support.

number_daily_cap_reached#

HTTP 429. Le numéro d'envoi a envoyé 1 000 messages au cours des dernières 24 heures (usage raisonnable), ou un lot ne tiendrait pas dans ce qui reste : requested et room indiquent combien.

Que faire : envoyez le reste plus tard, ou depuis un autre numéro.

message_rejected#

HTTP 422. Le message n'a pas pu être mis en file d'attente ; message indique pourquoi. Rien n'a été enregistré.

Que faire : corrigez ce que décrit message et renvoyez.

message_not_found#

HTTP 404. Aucun message avec cet identifiant pour cette clé : il n'existe pas, appartient à un autre espace de travail, ou a été envoyé depuis un numéro que la clé ne peut pas utiliser. Une clé de test ne voit que ses propres messages de test, et une clé réelle ne les voit jamais.

Que faire : vérifiez l'identifiant, et que vous utilisez le même type de clé (réelle ou de test) que celle qui a créé le message.

not_cancellable#

HTTP 409. Seul un message en attente (queued ou scheduled) peut être annulé, et celui-ci n'attend plus. status dans l'erreur indique son état actuel, par exemple sent ou cancelled.

Que faire : il n'y a rien à annuler. Un message déjà envoyé ne peut pas être rappelé.

Rappels#

invalid_cron#

HTTP 400. schedule.cron n'est pas une expression cron en 5 parties, ou décrit une date qui n'arrive jamais (comme le 31 février).

Que faire : écrivez la minute, l'heure, le jour du mois, le mois et le jour de la semaine, comme 0 9 * * 1 pour le lundi à 09:00. Voir Planning.

invalid_timezone#

HTTP 400. schedule.timezone n'est pas un nom de fuseau horaire IANA.

Que faire : utilisez un nom comme Asia/Kolkata, Europe/London ou America/New_York, pas une abréviation comme IST ni un décalage comme +05:30. Consultez la référence des fuseaux horaires.

number_not_connected#

HTTP 422. Le from du rappel n'est pas un numéro connecté de cet espace de travail.

Que faire : connectez d'abord le numéro, choisissez-en un connecté, ou omettez from (null) pour que n'importe quel numéro connecté l'envoie.

reminder_not_found#

HTTP 404. Aucun rappel avec cet identifiant : il n'existe pas, a été supprimé, ou envoie depuis un numéro que la clé ne peut pas utiliser.

Que faire : vérifiez l'identifiant avec Lister les rappels.

Médias#

file_too_large#

HTTP 413. Le fichier téléversé dépasse 64 Mo.

Que faire : compressez-le ou découpez-le ; pour une vidéo, réduisez sa résolution.

unsupported_file_type#

HTTP 415. Le type du fichier ne peut pas être envoyé sur WhatsApp. Le type est déduit de l'extension à la fin du nom du fichier.

Que faire : vérifiez les types que vous pouvez téléverser, et gardez l'extension dans le nom (price-list.pdf, et non price-list).

storage_full#

HTTP 422. Le fichier ne tient pas dans le Répertoire média de l'espace de travail pour son forfait. used et limit indiquent l'espace utilisé et autorisé, en octets.

Que faire : supprimez les fichiers dont vous n'avez plus besoin, ou passez à un forfait avec plus de stockage.

media_in_use#

HTTP 409. Le fichier ne peut pas encore être supprimé : quelque chose doit encore l'envoyer (un message en attente, y compris celui d'une campagne, un rappel actif ou un déclencheur Google Sheets actif). count indique combien.

Que faire : annulez-les ou modifiez-les d'abord, ou attendez que les messages en attente soient partis.

upload_failed#

HTTP 502. Le fichier n'a pas pu être enregistré de notre côté.

Que faire : réessayez, avec la même Idempotency-Key.

Vérifications de numéros#

no_valid_numbers#

HTTP 422. Aucune des entrées de numbers n'est un numéro de téléphone. skipped indique combien il y avait d'entrées.

Que faire : envoyez des numéros au format international avec +, un par entrée, comme +919876543210.

too_many_numbers#

HTTP 422. La vérification contient plus de numéros qu'une vérification ne peut en avoir : plus de 10 000 entrées dans la requête, ou plus de numéros que le forfait n'en autorise par vérification. count et limit indiquent combien.

Que faire : découpez la liste en plusieurs vérifications. Voir Limites du forfait.

number_check_quota_reached#

HTTP 422. La vérification dépasserait les vérifications de numéros du forfait pour cette période de facturation. requested, used et limit indiquent combien.

Que faire : vérifiez moins de numéros, attendez la prochaine période de facturation, ou passez à un forfait supérieur.

number_check_not_found#

HTTP 404. Aucune vérification de numéros avec cet identifiant dans l'espace de travail.

Que faire : vérifiez l'identifiant avec Lister les vérifications.

Numéros#

plan_required#

HTTP 403. Le forfait de l'espace de travail n'inclut pas ce dont cette requête a besoin : l'API du code QR pour connecter un numéro, les rappels pour créer, modifier ou réactiver un rappel, ou la vérification de numéros pour lancer une vérification de numéros.

Que faire : un propriétaire peut passer à un forfait supérieur sur la page Tarifs. La lecture de ce qui existe déjà fonctionne avec n'importe quel forfait.

number_limit_reached#

HTTP 403. Le forfait n'a plus de place pour un autre numéro.

Que faire : reconnectez un numéro existant avec number_id, supprimez un numéro que vous n'utilisez plus, ou passez à un forfait supérieur.

already_connected#

HTTP 409. Le numéro est déjà connecté.

Que faire : rien : vous pouvez envoyer depuis ce numéro. Vérifiez avec Obtenir un numéro.

connect_in_progress#

HTTP 409. Ce numéro est en cours de connexion. number_id dans l'erreur indique lequel.

Que faire : interrogez GET /numbers/{id} pour ce numéro au lieu de refaire la demande. Après 10 minutes sans scan, vous pouvez refaire la demande.

Webhooks#

invalid_webhook_url#

HTTP 422. url n'est pas une adresse https:// publique : c'est une adresse http://, elle est mal formée, ou elle pointe vers une adresse privée ou locale.

Que faire : utilisez une adresse https:// à laquelle votre serveur répond depuis Internet. Pour tester sur votre ordinateur, utilisez un service de tunnel qui vous fournit une adresse https:// publique.

webhook_limit_reached#

HTTP 403. L'espace de travail a déjà 5 endpoints de webhook.

Que faire : supprimez celui que vous n'utilisez plus. Un seul endpoint peut recevoir tous les types d'événements.

webhook_not_found#

HTTP 404. Aucun endpoint de webhook avec cet identifiant : il n'existe pas ou a été supprimé. Tester ou remplacer le secret d'un endpoint arrêté donne aussi cette réponse ; le lire affiche active: false.

Que faire : vérifiez l'identifiant avec Lister les endpoints. S'il s'est arrêté, ajoutez-le de nouveau.

Mode test#

test_mode_unsupported#

HTTP 403. Une clé de test (wbz_test_…) peut envoyer, lire et annuler des messages de test et lire le reste de l'espace de travail, mais pas modifier autre chose : connecter un numéro, créer, modifier ou supprimer des rappels, téléverser ou supprimer des médias, lancer une vérification de numéros, ou gérer des endpoints de webhook. Le filtre status de GET /messages n'est pas non plus pris en charge pour les clés de test.

Que faire : utilisez une clé réelle (wbz_live_…) pour ces requêtes. Voir Mode test.