Base de connaissances GetMyBot

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 HTTPSignification
200 OKRequête réussie, données dans le corps
201 CreatedNouvelle ressource créée, pour certains endpoints POST
204 No ContentSuccès sans corps, pour certaines suppressions
400 Bad RequestCorps ou paramètres incorrects
401 UnauthorizedJeton absent, incorrect ou expiré, ou route inaccessible par PAT
402 Payment RequiredForfait ou quota insuffisant, par exemple le stockage média propre qui exige premium
403 ForbiddenPortée manquante ou droit insuffisant sur le compte (missing cabinet right, voir Compte du jeton)
404 Not FoundRessource introuvable ou ne vous appartenant pas
409 ConflictConflit 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 LargeCorps trop grand, voir limites. Avec Idempotency-Key, le seuil distinct est 64 KiB
422 Unprocessable EntityJSON 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 RequestsLimite de fréquence dépassée, voir limites
500 Internal Server ErrorErreur 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 : 409 et Retry-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

  1. Générez l’UUID avant la première tentative et conservez-le avec la tâche.
  2. Envoyez la requête avec cette clé.
  3. Après une coupure, un délai dépassé, 5xx ou 429, réessayez avec la même clé.
  4. Sur 409, attendez Retry-After puis réessayez avec la même clé.
  5. 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