API
Erreurs et limites de débit
Ce que signifie chaque code de statut, et comment exploiter les clés — rotation, révocation, fuite.
Les erreurs reviennent sous forme de statut HTTP avec un corps JSON portant statusCode et message. Le message est écrit pour la personne qui lit le log, pas pour être filtré par motif — branchez sur le statut.
Ce que signifie chaque statut
| Statut | Signification |
|---|---|
401 | Clé inconnue, révoquée ou expirée — ou présentée hors de sa liste blanche d’IP. Un seul message pour les quatre, car ces différences sont précisément ce qu’un sondeur utiliserait pour cartographier l’espace des clés. |
403 « not available to API keys » | L’endpoint est réservé aux sessions. Voir ce qu’une clé peut atteindre. |
403 « missing the … scope » | L’endpoint est ouvert ; votre clé n’a pas le scope. |
403 « restricted to other projects » | Le projectIds de la clé n’inclut pas le projet auquel appartient cette ressource. |
403 « account … is not active » | Le propriétaire a été suspendu ou banni. Ses clés se sont arrêtées à cette requête même. |
400 « already holds 50 live API keys » | Le plafond par compte. Révoquez-en une — les clés révoquées et expirées ne comptent pas. |
400 | Le corps de la requête n’a pas validé. Le message nomme le champ. |
404 | Ressource inexistante — ou invisible pour vous. Les deux ne sont pas distingués, pour la même raison que le 401. |
429 | Débit limité. Temporisez et réessayez ; la réponse suit la sémantique habituelle de Retry-After. |
Un refus lié aux quotas est aussi un
4xx — un projet à son plafond refuse explicitement le travail supplémentaire plutôt que de se dégrader en silence.Exploiter les clés dans la durée
- Faire tourner par recouvrement
- Frappez la remplaçante, déployez-la, puis révoquez l’ancienne. La révocation est immédiate : l’ordre compte.
lastUsedAt/lastUsedIp- Horodatés au plus une fois par minute et par clé — le faire à chaque requête transformerait une lecture en écriture et ferait contendre une clé de CI très sollicitée sur sa propre ligne. Suffisant pour répondre « est-ce que ça sert encore ? » ; ce n’est pas un journal d’accès.
- Le journal d’audit
- Enregistre création, révocation et suppression avec le nom de la clé, son préfixe, et les scopes réellement détenus — l’ensemble assaini, pas ce qui a été demandé : une ligne n’affiche jamais un octroi qui a été écarté. Voir audit.
Une clé a fuité
- 01Révoquez-la. Effet immédiat, et la ligne est conservée pour que le journal d’audit survive. La suppression fonctionne aussi mais détruit les preuves.
- 02Lisez le journal d’audit pour savoir ce qu’elle a fait pendant qu’elle circulait.
- 03Frappez une remplaçante aux scopes plus étroits si l’incident a montré que l’ancienne dépassait le besoin réel.
Si la clé n’est pas la vôtre, tout administrateur disposant de users:manage peut la révoquer — voir arrêter une clé qui n’est pas la vôtre. Vous n’avez pas besoin de son détenteur.
Comme une clé ne dépasse jamais son propriétaire, le rayon d’impact est borné par les droits de ce compte. C’est l’argument pour frapper les clés sous un compte dédié plutôt que sous votre propre login administrateur.