# Dépannage API : erreurs courantes

_API · Lecture de 4 min · Mis à jour 2026-10-23 · https://lanachat.ai/guides/fr/api-troubleshooting/_

Chaque endpoint dans la référence est marqué **Planned** aujourd’hui : c’est le contrat publié mais il ne répond pas encore. Cette page liste les erreurs que l’API renverra, pour que votre code puisse les gérer dès le premier jour.

## Lisez d’abord l’erreur

Chaque erreur répond avec un statut 4xx ou 5xx et le même corps :

```json
{ "error": { "code": "forbidden", "message": "…" } }
```

`message` est une phrase en anglais simple qui explique ce qui n’a pas fonctionné. Enregistrez-la, mais faites une branche dans votre code selon `code`, jamais selon `message`.

## 401 unauthorized

L’API n’a pas accepté votre token. Vérifiez, dans cet ordre :

1. L’en-tête est exactement `Authorization: Bearer <token>`, avec le mot `Bearer` et un espace.
2. Le token a été copié en entier. Il n’est affiché qu’une fois, lors de sa création.
3. Le token est toujours actif. Dans **Users › API & MCP**, le tableau **Access tokens** montre la date d’expiration et le statut de chaque token, et **Show revoked tokens** liste les anciens.
4. S’il a expiré ou a été révoqué, créez-en un nouveau (ou **Rotate** le) et mettez à jour votre variable d’environnement.

## 403 forbidden

Le token est valide mais n’a pas la permission requise par l’endpoint. Chaque endpoint dans la référence liste sa permission, comme `can_fan_read` ou `can_sales_read`.

1. Trouvez la permission dans la colonne **Permission** de l’endpoint.
2. Dans **Users › API & MCP**, cliquez sur **Edit** sur le token et cochez-la.
3. Appelez `GET /v1/workspace` : la réponse liste ce que le token peut faire.

Un `403` revient aussi quand un token qui n’est pas un token propriétaire envoie l’en-tête `LanaChat-Workspace`. Supprimez-le.

## 429 rate_limited

Chaque token peut envoyer 600 requêtes par minute. Chaque réponse porte `RateLimit-Remaining` et `RateLimit-Reset`.

- Attendez le nombre de secondes indiqué dans `Retry-After`, puis réessayez.
- Parcourez les listes avec `limit=100` au lieu d’un appel par élément.
- L’envoi de messages aux fans est aussi limité par les propres restrictions de Telegram : voir [Telegram accounts and pools](https://lanachat.ai/guides/fr/api-telegram-accounts/).

## Les autres codes

| Status | `code` | Que faire |
|---|---|---|
| 400 | `invalid_request` | Un champ est manquant ou mal formaté : `message` indique lequel |
| 402 | `insufficient_balance` | Rechargez avant d’acheter |
| 404 | `not_found` | L’id n’existe pas dans cet espace de travail : vérifiez que vous utilisez le bon token |
| 409 | `conflict` | La modification enfreint une règle, ou une `Idempotency-Key` a été réutilisée avec un corps différent |
| 500 | `server_error` | Réessayez plus tard avec la même `Idempotency-Key` |

Envoyez une `Idempotency-Key` à chaque `POST` : une nouvelle tentative ne fera jamais le travail deux fois. L’aide dans [the quick start](https://lanachat.ai/guides/fr/api-overview/) réessaie les `429` et `5xx` pour vous.

## Webhooks qui échouent

Une livraison est considérée comme échouée quand votre serveur ne répond pas par un `2xx` en 10 secondes.

1. **Répondez vite.** Retournez un `2xx` immédiatement, puis faites le travail lent en arrière-plan.
2. **Vérifiez la signature sur le corps brut**, avant tout parsing JSON. Un corps parsé puis re-sérialisé ne correspond jamais.
3. **Vérifiez l’horloge de votre serveur.** Un timestamp vieux de plus de 5 minutes est refusé par le code d’exemple, donc une horloge qui dérive rejette toutes les livraisons.
4. **Acceptez les deux valeurs `v1`** pendant une rotation de secret.
5. **Testez** avec `POST /webhooks/{id}/test` (Planned), qui envoie un `ping`, et renvoyez une livraison avec `/deliveries/{delivery_id}/retry` (Planned) une fois que vous avez corrigé votre côté.

Les livraisons échouées sont réessayées 8 fois sur environ 24 heures. Après 3 jours d’échecs, l’endpoint est mis en pause ; reprenez-le avec `PATCH /webhooks/{id}` (Planned). Le même événement peut arriver deux fois : ignorez les doublons par `id`. Voir [Webhooks](https://lanachat.ai/guides/fr/api-webhooks/).

## Toujours bloqué ?

Ouvrez la bulle d’aide en bas à droite de la Console et écrivez à l’équipe en indiquant l’endpoint, le statut, le `code` et l’heure de l’appel. Ne collez jamais le token lui-même. Voir [Get help](https://lanachat.ai/guides/fr/get-help/).

## Articles liés

- [API LanaChat : démarrage rapide, authentification et erreurs](https://lanachat.ai/guides/fr/api-overview/)
- [API : webhooks, événements et signatures](https://lanachat.ai/guides/fr/api-webhooks/)
- [API : membres de l’équipe, rôles et jetons d’accès](https://lanachat.ai/guides/fr/api-team/)
- [Recettes rapides API : copier, coller, exécuter](https://lanachat.ai/guides/fr/api-recipes/)