# Erreurs, limites et idempotence

> L'enveloppe d'erreur de l'API WhatSetter, chaque code avec son statut HTTP, les en-têtes de débit et de quota, l'Idempotency-Key et comment réessayer.

Source: https://docs.whatsetter.com/fr/developers/errors/

Chaque erreur de l'API WhatSetter a la même forme et un `code` stable. Cette page les liste toutes, décrit les en-têtes qui traduisent tes limites, et dit quoi faire quand un appel échoue.

## L'enveloppe d'erreur

```json
{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key is missing the \"messages:send\" scope."
  }
}
```

- `code` est stable : fais tes branchements dessus.
- `message` est pour les humains et peut changer. Logue-le, ne le parse pas.
- Le statut HTTP correspond au code (voir le tableau). Les réponses de succès utilisent `{ "data": … }`, et les listes ajoutent `{ "pagination": { "has_more", "next_cursor" } }`.

## Les codes d'erreur

| HTTP | `code` | Quand ça arrive | Quoi faire |
|---|---|---|---|
| 400 | `validation_error` | Le chemin contient un encodage d'URL invalide (par exemple `%ZZ`). | Corrige l'URL. |
| 401 | `missing_api_key` | Ni en-tête `Authorization: Bearer`, ni en-tête `X-Api-Key`. | Envoie la clé. |
| 401 | `invalid_api_key` | La clé est inconnue, révoquée, ou n'a pas le format `ws_live_`. | Vérifie la clé, ou crées-en une nouvelle. |
| 402 | `plan_limit_reached` | `POST /campaigns/{id}/resume` alors que le quota de campagnes actives de ton plan est plein. Ajout d'une réponse à une base de connaissances avec un plan qui n'en ajoute pas, ou à une base qui en contient déjà 200. | Mets une autre campagne en pause, retire une réponse, ou change de plan. |
| 403 | `insufficient_scope` | La clé n'a pas le scope que cet endpoint demande. Le message le nomme. | Crée une clé avec ce scope. |
| 403 | `not_in_plan` | Listes, groupes, liens et webhooks sur un espace Social : ils demandent un forfait WhatsApp. | Passe à Starter ou plus, ou retire cet appel. |
| 404 | `not_found` | Route inconnue, ou la ressource n'existe pas, ou elle appartient à un autre espace. | Vérifie l'identifiant et le chemin. |
| 409 | `invalid_state` | Mettre en pause une campagne qui n'est pas active, relancer une campagne qui n'est pas en pause, ajouter un lead à une campagne qui n'est pas active, ou passer la main sur un lead sans conversation. | Lis le message et change l'état dans le dashboard. |
| 409 | `lead_not_contacted` | `POST /messages` sur un lead à qui personne n'a encore écrit. | Le premier contact passe par une liste et une campagne. |
| 409 | `request_in_flight` | Une requête avec la même `Idempotency-Key` est encore en cours. | Attends quelques secondes, puis réessaie avec la même clé. |
| 409 | `already_blocked` | `POST /blocked-contacts` pour un numéro ou un indicatif déjà dans la liste. | Rien : il est déjà bloqué. |
| 409 | `version_conflict` | `PUT /campaigns/{id}/prompts/{type}`, ou `POST …/versions/{versionId}/restore`, avec un `if_version` qui n'est plus la version en ligne (de cette variante, pendant un test A/B). | Relis le prompt, puis envoie ta modification ou ta restauration. |
| 409 | `draft_pending` | Une écriture ou une restauration de prompt pendant qu'un brouillon enregistré dans le dashboard attend sur ce texte. | Compare le brouillon au texte en service, puis publie-le ou renvoie l'appel avec `ignore_draft`. |
| 409 | `variant_required` | Une écriture de prompt pendant un test A/B, sans `variant`. | Nomme la variante que tu modifies. |
| 409 | `variant_not_live` | Une écriture ou une restauration de prompt sur une variante sortie du test pendant qu'une autre sert. | Modifie une variante qui sert, ou remets-la dans le test depuis le dashboard. |
| 422 | `validation_error` | Un paramètre ou un champ du corps manque ou est invalide : `limit` hors de 1 à 100, une date qui n'est pas en ISO 8601, un `text` vide, un id de membre inconnu dans `assigned_to`. | Corrige la requête. Réessayer à l'identique échouera encore. |
| 429 | `rate_limited` | Plus de requêtes par minute que ton plan n'en autorise. | Attends `Retry-After` secondes, puis réessaie. |
| 429 | `quota_exceeded` | Le quota WhatsApp quotidien du numéro émetteur est atteint (il se remet à zéro à minuit UTC), ou un plafond de l'espace est atteint : 200 listes, 10 souscriptions webhook, 500 contacts bloqués. | Attends `X-Quota-Reset`, ou supprime ce qui ne sert plus. |
| 500 | `internal_error` | Une erreur inattendue de notre côté, ou le backend de messagerie n'est pas configuré. | Réessaie plus tard. Contacte le support si ça persiste. |
| 500 | `server_error` | Le contrôle de l'agent n'est pas configuré sur ce déploiement (`handoff`, `resume`). | Contacte le support. |
| 502 | `send_failed` | Le moteur WhatsApp n'a pas confirmé l'envoi. | Réessaie avec la même `Idempotency-Key`. Sans clé, relis la conversation avant de renvoyer. |
| 502 | `upstream_error` | Le workflow derrière `handoff`, `resume` ou `POST /campaigns/{id}/leads` a refusé l'appel ou était injoignable. | Réessaie dans un instant. |
| 503 | `agent_disconnected` | Le numéro WhatsApp de la campagne est déconnecté, ou aucun numéro n'y est rattaché. | Reconnecte le numéro dans le dashboard. |
| 503 | `service_unavailable` | Le backend d'authentification est indisponible. | Réessaie dans quelques secondes. |

## Les en-têtes de débit

Les requêtes sont comptées par espace et par minute, toutes clés confondues, avec une limite fixée par ton plan (30 à 1000 par minute, voir [Authentification et permissions](/fr/developers/authentication/)). Chaque réponse porte :

```
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 2026-09-19T10:01:00.000Z
```

Quand la limite est dépassée, la réponse est `429 rate_limited` et ajoute `Retry-After` en secondes :

```
HTTP/1.1 429 Too Many Requests
Retry-After: 23
```

## Les en-têtes de quota

L'envoi de messages a un second budget, séparé : le **quota quotidien du numéro WhatsApp**, le même que celui du moteur de campagne (voir la [protection anti-ban](/fr/dashboard/anti-ban/)). Un `POST /messages` réussi le renvoie :

```
X-Quota-Limit: 150
X-Quota-Remaining: 149
X-Quota-Reset: 2026-09-20T00:00:00.000Z
```

Les mêmes chiffres sont dans le corps sous `data.quota` (`limit`, `used`, `remaining`, `resets_at`). Quand le quota est atteint tu reçois `429 quota_exceeded`. Il se remet à zéro à minuit UTC. `quota_exceeded` sert aussi pour les plafonds de l'espace listés dans le tableau ci-dessus.

## L'idempotence

`POST /messages` peut être réessayé sans risque si tu envoies un en-tête `Idempotency-Key` : n'importe quelle chaîne unique de 200 caractères au plus, par exemple un UUID par intention d'envoi.

```bash
curl -X POST https://app.whatsetter.com/api/v1/messages \
  -H "Authorization: Bearer $WHATSETTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4d3f9b2a-7c1e-4a8b-9f0d-2e6c8a1b3d5f" \
  -d '{"lead_id":"66f1a2b3c4d5e6f7a8b9c0d1","text":"On se confirme pour demain 14h ?"}'
```

Ce que fait la clé :

- Une clé qui a déjà produit une réponse la **rejoue** avec l'en-tête `X-Idempotent-Replay: true`. Aucun second message n'est envoyé.
- Une nouvelle tentative lancée pendant que la première tourne encore reçoit `409 request_in_flight`. Attends quelques secondes et réessaie avec la même clé.
- Si un envoi expire ou répond `502 send_failed`, réessayer avec la **même** clé est sûr : WhatSetter rejoue le résultat enregistré ou répond `409` tant que ça se stabilise. Il n'envoie jamais deux fois.
- Les clés sont propres à ton espace et mémorisées 15 minutes.

> **Envoie toujours une Idempotency-Key**
Sans clé, une nouvelle tentative après un timeout peut livrer deux fois le même message WhatsApp à une vraie personne. Le [serveur MCP](/fr/developers/mcp/) en ajoute une automatiquement à chaque appel de `send_whatsapp_message`.

## L'en-tête de version

Chaque réponse porte `X-Api-Version: 2026-10`, la version du contrat REST. Les charges utiles des webhooks ont leur propre champ `api_version` (`2026-06-01`), décrit sur la page [webhooks](/fr/developers/webhooks/).

## Conseils pour réessayer

| Réponse | Réessayer ? | Comment |
|---|---|---|
| `429 rate_limited` | Oui | Attends `Retry-After` secondes. |
| `429 quota_exceeded` sur `POST /messages` | Oui, demain | Attends `X-Quota-Reset` (minuit UTC). |
| `502 send_failed`, `502 upstream_error`, `503 *` | Oui | Backoff exponentiel, à partir de quelques secondes. Pour `POST /messages`, réutilise la même `Idempotency-Key`. |
| `500 internal_error` | Une fois, plus tard | Si ça persiste, contacte le support avec le chemin et l'heure de la requête. |
| `409 request_in_flight` | Oui | Attends quelques secondes, même `Idempotency-Key`. |
| Tout autre `4xx` | Non | La requête elle-même est fausse. Corrige-la d'abord. |

## Voir aussi

- [Authentification et permissions](/fr/developers/authentication/)
- [Guide Messages](/fr/developers/guides/messages/)
- [Protection anti-ban](/fr/dashboard/anti-ban/)
