Dépannage API : erreurs courantes
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 :
{ "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 :
- L’en-tête est exactement
Authorization: Bearer <token>, avec le motBeareret un espace. - Le token a été copié en entier. Il n’est affiché qu’une fois, lors de sa création.
- 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.
- 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.
- Trouvez la permission dans la colonne Permission de l’endpoint.
- Dans Users › API & MCP, cliquez sur Edit sur le token et cochez-la.
- 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=100au 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.
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 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.
- Répondez vite. Retournez un
2xximmédiatement, puis faites le travail lent en arrière-plan. - Vérifiez la signature sur le corps brut, avant tout parsing JSON. Un corps parsé puis re-sérialisé ne correspond jamais.
- 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.
- Acceptez les deux valeurs
v1pendant une rotation de secret. - Testez avec
POST /webhooks/{id}/test(Planned), qui envoie unping, 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.
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.