Une intégration qui tourne seule doit pouvoir se surveiller : combien d’appels elle passe, quand elle a appelé pour la dernière fois, et pourquoi ses appels sont refusés. Cet article présente la fiche d’un jeton, son journal d’appels, les limites qui s’appliquent et la consommation de la plateforme API, puis donne les causes de refus les plus courantes et leur remède. Il s’adresse aux administrateurs qui gèrent les intégrations.
Avant de commencer #
- Le droit « Voir les tokens API » suffit pour lire la liste, les fiches et les journaux, dans Paramètres › Gérer Illizeo › Jetons API.
- Corriger un jeton (droits, limite, expiration, réactivation) demande le droit « Créer / éditer / révoquer un token » au palier Exécuter (voir Créer et gérer les jetons API).
La fiche d’un jeton #
Dans la liste, cliquez sur le nom d’un jeton ou sur l’icône Voir. La fiche indique :
- Jeton (masqué) : le début de la valeur ; la valeur complète n’a été montrée qu’une fois, à la création ;
- Droits, Expire le (ou Jamais) ;
- Limite de débit : la limite réellement appliquée, avec la mention « (par défaut) » quand aucune n’a été saisie ;
- Plafond journalier : le nombre de requêtes permises par jour ;
- Dernière utilisation, avec l’adresse IP de l’appel ;
- Créé le (et, le cas échéant, la date de révocation) et Créé par.
Sous la fiche, quatre compteurs donnent le nombre de requêtes enregistrées : sur toute la durée de conservation du journal (90 jours), sur les dernières 24 heures, les 7 et les 30 derniers jours.
Le journal des appels #
Le tableau Derniers appels liste les vingt appels les plus récents : Point de terminaison, Méthode, Statut (le code HTTP de la réponse), Durée, IP et Date. Un statut 2xx est un succès ; un 403 ou un 404 signale un refus de droit ou de périmètre (voir plus bas).
- Le journal ne retient que les appels qui ont passé les contrôles du jeton. Un appel refusé parce que le jeton est inconnu, expiré, désactivé, privé du droit demandé ou au-delà de sa limite n’y figure pas : c’est la réponse reçue par l’intégration qui en donne la raison.
- La date de dernière utilisation est mise à jour au plus une fois par minute.
- Les lignes de plus de 90 jours sont effacées chaque nuit.
Les limites d’un jeton #
| Limite | Valeur | Au-delà |
|---|---|---|
| Par minute, pour le jeton | Celle saisie sur le jeton, sinon 60 requêtes | Réponse 429, à refaire après le délai donné par l’en-tête Retry-After |
| Par jour, pour le jeton | 10 000 requêtes, remises à zéro à minuit UTC | Réponse 429 jusqu’au lendemain |
| Par minute, pour l’entreprise | 600 requêtes, tous jetons confondus | Réponse 429 pour tous les jetons |
| Taille d’une requête | 5 Mo, corps et fichiers compris | Réponse 413 |
Seule la limite par minute du jeton se règle, de 1 à 10 000, en modifiant le jeton.
La consommation de la plateforme API #
La carte Plateforme API, en tête de la liste des jetons, résume la période en cours : ses dates, les unités consommées (et celles incluses dans votre abonnement, s’il en prévoit), la date de remise à zéro, et le détail Appels API, Webhooks livrés, Exports planifiés. Chaque appel passé, chaque webhook livré et chaque fichier d’export planifié produit compte une unité.
- Pendant l’essai, aucun quota ne s’applique : seule la limite de débit compte.
- Le plafond de sécurité se règle dans l’abonnement, par les personnes qui le gèrent ; le lien Gérer la consommation dans l’abonnement y mène si vous y avez accès. Une fois ce plafond atteint, l’API répond 429 et les webhooks et exports planifiés s’arrêtent jusqu’à la période suivante ; la carte l’annonce.
Quand un jeton ne répond plus #
Chaque refus porte un code lisible dans le champ error_code de la réponse. Demandez-le à la personne qui suit l’intégration :
| Situation | Réponse reçue | Que faire |
|---|---|---|
| L’en-tête d’authentification manque ou est mal formé | 401, JETON_ABSENT |
Envoyer Authorization: Bearer suivi de la valeur complète du jeton. |
| Valeur inconnue : erreur de copie, jeton régénéré depuis, ou jeton révoqué | 401, JETON_INVALIDE |
Transmettre la valeur actuelle ; si le jeton est révoqué, en créer un nouveau. |
| Date d’expiration passée | 401, JETON_EXPIRE ; après le passage de nuit qui le rend inactif, 403, JETON_DESACTIVE |
Donner une nouvelle date d’expiration, puis réactiver le jeton. |
| Jeton désactivé | 403, JETON_DESACTIVE |
Réactiver le jeton dans la liste. |
| Le créateur du jeton n’est plus actif | 403, CREATEUR_INDISPONIBLE |
Créer un nouveau jeton depuis un compte actif. |
| Le droit appelé n’est pas coché sur le jeton | 403, SCOPE_MANQUANT, avec le droit attendu |
Modifier le jeton et cocher ce droit. |
| Le créateur n’a pas le droit de l’écran équivalent, ou le module ne lui est pas ouvert | 403 | Donner ce droit à l’un de ses rôles, ou lui assigner le module. |
| La personne ou l’objet demandé est hors du périmètre du créateur | 404 | Vérifier la population de ses rôles. |
| L’abonnement ne comprend pas l’accès à l’API | 403, FONCTIONNALITE_NON_INCLUSE |
Voir l’abonnement. |
| Limite par minute, par jour ou de l’entreprise atteinte | 429, LIMITE_DE_DEBIT, LIMITE_JOURNALIERE ou LIMITE_DE_DEBIT_TENANT |
Attendre le délai de Retry-After ; au besoin, relever la limite par minute du jeton. |
| Plafond de consommation atteint | 429, PLAFOND_DE_CONSOMMATION |
Revoir le plafond dans l’abonnement, ou attendre la période suivante. |
| Requête de plus de 5 Mo | 413, TAILLE_DE_REQUETE |
Découper l’envoi. |
À savoir #
- Un jeton n’envoie aucune alerte avant d’expirer : surveillez la date affichée dans la colonne Dernière utilisation de la liste.
- Toute réponse porte un identifiant dans son en-tête
X-Request-Id(repris dansrequest_idpour l’enveloppe standard) : citez-le dans une demande de support. - Les détails techniques (en-têtes, enveloppe des réponses, pagination) sont dans API publique : le guide du développeur.
Questions fréquentes #
L’intégration reçoit des 404 alors que la personne existe. #
Le jeton ne voit que ce que voit son créateur. Si la personne n’est pas dans la population de ses rôles, elle n’existe pas pour le jeton.
La fiche indique « Jamais » en dernière utilisation alors que l’intégration appelle. #
Ses appels sont refusés avant d’être comptés. Demandez le code d’erreur reçu et reportez-vous au tableau ci-dessus.
