Erreurs API
Comprendre une erreur API, savoir corriger ou réessayer, et répéter un paiement ou un envoi sans doublon.
Sur cette page
Si une requête échoue, regardez d’abord le code HTTP : 401 signale, par exemple, un problème d’accès, et 429 un excès de requêtes. Le champ error précise la cause. Une réponse réussie contient directement les données, sans enveloppe générale supplémentaire.
Format des erreurs
En cas d’échec, le serveur renvoie un objet JSON avec un seul champ error contenant un message :
{"error":"reaction not found"}
Appuyez-vous avant tout sur le code HTTP ; utilisez le texte error pour les journaux et les indications à l’utilisateur.
Codes de réponse
| Code HTTP | Signification |
|---|---|
200 OK | Requête réussie, données dans le corps |
201 Created | Nouvelle ressource créée, pour certains endpoints POST |
204 No Content | Succès sans corps, pour certaines suppressions |
400 Bad Request | Corps ou paramètres incorrects |
401 Unauthorized | Jeton absent, incorrect ou expiré, ou route inaccessible par PAT |
402 Payment Required | Forfait ou quota insuffisant, par exemple le stockage média propre qui exige premium |
403 Forbidden | Portée manquante ou droit insuffisant sur le compte (missing cabinet right, voir Compte du jeton) |
404 Not Found | Ressource introuvable ou ne vous appartenant pas |
409 Conflict | Conflit d’état, par exemple valeur unique en doublon ; avec Idempotency-Key, peut aussi signifier que l’opération est encore en cours |
413 Payload Too Large | Corps trop grand, voir limites. Avec Idempotency-Key, le seuil distinct est 64 KiB |
422 Unprocessable Entity | JSON valide mais données refusées par les règles du domaine ; avec Idempotency-Key, peut aussi signaler une clé déjà utilisée avec un corps différent |
429 Too Many Requests | Limite de fréquence dépassée, voir limites |
500 Internal Server Error | Erreur interne, réessayez plus tard |
Comment réagir
Considérez tous les codes 2xx comme des succès. Sur 401 ou 403, vérifiez le jeton, ses portées et vos droits dans le compte. Sur 429 et 5xx, réessayez avec un délai croissant de façon exponentielle.
Pour les autres 4xx, corrigez la requête avant de la répéter. Exception importante : 409 sur une requête avec Idempotency-Key signifie que la même opération est en cours, pas qu’elle est mauvaise. Ne l’abandonnez pas : le paiement ou l’envoi pourrait aboutir. Réessayez avec la même clé après le délai Retry-After indiqué.
Réessayer une opération payante : Idempotency-Key
La clé doit être un UUID canonique, en minuscules avec tirets, comme 9b1f0d4c-2f6a-4a5f-9a3f-1f2f3a4b5c6d. Une autre écriture est refusée avec 400.
Routes concernées
L’en-tête est facultatif, mais pris en compte sur les opérations dont la répétition coûte de l’argent ou lance un envoi massif :
POST /api/billing/topup: recharger le solde ;POST /api/billing/subscribe: souscrire un forfait ;POST /api/bots/{botID}/reactions/{reactionID}/broadcast: lancer une diffusion.
Il est au contraire obligatoire sur deux envois par opérateur : sans lui, 400 est renvoyé.
POST /api/bots/{botID}/users/{userID}/dialog/messages;POST /api/bots/{botID}/support/dialogs/{subscriberID}/templates.
Sur les autres routes, cet en-tête est ignoré. Ne le considérez pas comme une protection universelle : ailleurs, une répétition est une seconde requête.
Réponses du serveur
- Même clé, même corps, opération terminée : le serveur rejoue la réponse enregistrée lors de la première tentative, code et corps identiques, avec
Idempotent-Replay: true. L’opération n’a lieu qu’une fois. L’enregistrement vit une semaine. - Même clé, opération en cours :
409etRetry-After. Attendez puis réessayez avec la même clé ; une nouvelle clé pourrait créer un second débit. - Même clé, corps différent :
422. Le serveur ne peut pas deviner lequel des deux corps est voulu. Utilisez une nouvelle clé pour une nouvelle opération. - Corps supérieur à 64 KiB :
413. Ces opérations demandent de petits corps ; cette taille signale une erreur côté client.
Certains codes ne sont pas mémorisés avec la clé : 5xx, 408, 425 et 429. Ils signifient que la requête n’a pas été exécutée ; une nouvelle tentative avec la même clé peut donc accomplir le travail. Si le refus était mémorisé, chaque tentative suivante recevrait le même refus pendant une semaine.
Procédure pratique
- Générez l’UUID avant la première tentative et conservez-le avec la tâche.
- Envoyez la requête avec cette clé.
- Après une coupure, un délai dépassé,
5xxou429, réessayez avec la même clé. - Sur
409, attendezRetry-Afterpuis réessayez avec la même clé. - Ne créez une nouvelle clé que pour une opération réellement nouvelle.
L’erreur la plus fréquente consiste à générer une clé à chaque tentative. L’en-tête est alors présent, mais chaque tentative paraît être une opération distincte et la protection ne sert à rien.
Erreurs de l’IA et des scénarios
Managed AI fournit les codes not_available (fonction indisponible), not_entitled (pas de droit), budget_exceeded (budget épuisé), rate_limited (limite de fréquence), provider_unavailable (fournisseur indisponible) et schema_validation_failed (réponse non conforme au schéma). Ne réessayez que les erreurs pour lesquelles la réponse permet une nouvelle tentative, en gardant le même Idempotency-Key. Sur un 4xx autre que 429 ou une erreur de schéma, corrigez la requête : changer de fournisseur de modèle n’y remédiera pas.
Si Copilot renvoie stale_base, sa proposition de modification est obsolète : recréez-la à partir du scénario actuel. Modifier les règles d’analyse renvoie 409 si une autre requête les a déjà changées. Le recalcul analytique et la relecture d’une exécution sont des tâches à portée limitée : vérifiez l’état de la tâche démarrée avant d’en lancer une autre. La vérification d’une connexion Meta donne un code indiquant la cause. Elle n’inclut ni le corps de réponse Meta ni le jeton d’accès dans l’erreur.
Pour aller plus loin
- Authentification et jetons : détails sur
401et403. - Limites et tailles :
429et limites des corps. - Référence interactive : erreurs possibles pour chaque endpoint.