Erreurs

Qyvo renvoie des codes de statut HTTP conventionnels et une forme JSON d'erreur stable. Lorsqu'un envoi échoue parce que Meta a rejeté le message, le code d'erreur Meta sous-jacent est propagé pour que vous puissiez le gérer proprement.

Forme de l'erreur

Chaque réponse d'erreur est en JSON avec au minimum un champ error :

{
  "error": "Template not found"
}

Les échecs de validation (format Laravel) incluent un message et une carte errors indexée par champ :

{
  "message": "The given data was invalid.",
  "errors": {
    "phone": ["The phone field is required."],
    "template_id": ["The template id must be a valid UUID."]
  }
}

Certains endpoints ajoutent des détails structurés pour vous aider à corriger le problème dans le code :

{
  "error": "Template requires variables that were not provided.",
  "expected_placeholders": ["1", "2"],
  "missing": ["2"]
}

Codes de statut HTTP

Code	Signification	Quand vous le voyez
200	OK	Lecture ou envoi réussi
201	Created	Création de ressource (contact, session de séquence, …)
401	Unauthenticated	En-tête Authorization manquant ou invalide, jeton révoqué
403	Forbidden	Jeton valide mais sans le scope requis (rare aujourd'hui — chaque jeton possède mcp)
404	Not found	La ressource n'existe pas ou n'appartient pas à votre tenant
422	Unprocessable	Validation échouée, règle métier rejetée, ou aucun compte WhatsApp configuré
429	Too many requests	Quota dépassé — voir Limites de débit
5xx	Erreur serveur	Transitoire — réessayez avec un backoff

Erreurs Qyvo courantes

Statut	Texte error	Pourquoi
401	Unauthenticated.	Jeton manquant/erroné/révoqué
404	Personal access client not found	Problème d'installation backend — contactez le support
404	Contact not found	Le téléphone ou le contact_id ne correspond à aucun contact dans votre tenant
404	Template not found	L'UUID template_id n'existe pas dans votre tenant
404	Sequence not found or not published	La séquence est en brouillon — publiez-la d'abord
404	Flow not found or not published	Idem pour les flows
422	No workspace configured for this account.	L'utilisateur derrière le jeton n'a pas de tenant
422	No WhatsApp account configured	Le tenant n'a pas de ligne WabaAccount — onboardez d'abord un numéro
422	Either contact_id or phone is required	L'endpoint accepte l'un ou l'autre ; vous n'avez envoyé ni l'un ni l'autre
422	Template requires variables that were not provided.	Le corps a des {{1}} etc. mais vous ne les avez pas passés dans variables
422	Template has no approved translation to send.	Le template est en PENDING ou REJECTED chez Meta

Codes d'erreur Meta WhatsApp

Lorsque l'envoi atteint réellement Meta et échoue, le message d'erreur Meta remonte dans le champ error d'une réponse 422. Les plus fréquents :

Code Meta	Signification	Quoi faire
132001	Le nom du template n'existe pas dans cette langue	Synchronisez les templates et confirmez que la langue a une traduction APPROVED. Voir l'outil MCP sync_templates.
132012	Le format du paramètre ne correspond pas	Le nombre ou les types de vos variables ne correspondent pas au corps du template — vérifiez les placeholders du template
131026	Message non délivrable	Le téléphone destinataire n'est pas sur WhatsApp, ou n'a pas opt-in
131047	Re-engagement message	La fenêtre de service client de 24 heures est fermée. Envoyez un template au lieu d'un texte libre.
131051	Type de message non pris en charge	Vous avez envoyé une URL de média rejetée par Meta (taille, format, hôte)
131056	Limite de débit par paire atteinte	Limite Meta par paire (expéditeur→destinataire). Backoff et réessayez.
133010	Numéro de téléphone non enregistré	Le numéro WhatsApp Business n'est pas enregistré sur Cloud API du côté Meta

Idempotence

L'API Qyvo ne prend pas en charge actuellement un en-tête Idempotency-Key. Deux appels consécutifs à send-template-message avec le même payload enverront deux messages.

Pour dédupliquer de votre côté :

• Sur create-contact, l'endpoint est upsert par (tenant_id, phone) — appeler deux fois avec le même téléphone renvoie le contact existant, pas de doublons.
• Sur trigger-sequence / trigger-flow, une session running existante pour la même paire (sequence_id, contact_id) renvoie {status: "already_running"} au lieu d'en démarrer une seconde.
• Sur les envois de messages, dédupliquez au niveau applicatif (p. ex. verrou sur order_id avant d'appeler send-template-message).

Conseils de débogage

• curl -i pour voir les en-têtes — X-RateLimit-Remaining, Retry-After, request id.
• L'Inbox du tableau de bord montre les derniers messages failed avec la même error renvoyée par Meta. Si un envoi renvoie 422, le message apparaît également là avec status: failed pour la traçabilité d'audit.
• Les templates en PENDING ou REJECTED ne s'enverront pas ; vérifiez Paramètres → WhatsApp → Templates et resynchronisez depuis Meta.