La cadence, et le temps qu'on se donne
Se cadencer demande de connaître le plafond avant de s'y cogner. Les voici, tels qu'ils sont appliqués — et chaque réponse les porte, celles qui réussissent comprises : X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Window. Ralentis en lisant Remaining, plutôt qu'en attendant le 429.
| Ce qui est borné | Cadence | Compté par | Détail |
|---|---|---|---|
| Toute la surface | 60 / 60 s | par clé (ou par client OAuth) | Compté sur l’ensemble des appels /api/v1 et /api/mcp du même porteur. |
| Générer et rejouer une recette | 10 / 10 s | par compte | Fenêtre PARTAGÉE avec l’éditeur de l’app : la clé ne contourne pas la cadence. |
| Créer un document | 10 / 10 s | par compte | Gratuit en crédits — la cadence est sa seule borne. |
| Créer un projet | 10 / 10 s | par compte | Gratuit en crédits — la cadence est sa seule borne. |
| Déposer une source (boîte de réception) | 30 / 60 s | par compte | Gratuit et réversible : borné pour éviter qu’un script remplisse la boîte. |
| Archiver, mettre à la corbeille ou restaurer | 10 / 60 s | par clé (ou client OAuth) | Lots de 10 maximum, prévisualisables avec dryRun. Aucune purge définitive par API/MCP. |
| Vérifier un certificat (sans clé) | 60 / 60 s | par adresse IP | La seule opération ouverte sans compte — donc le seul plafond qui se compte sur l’appelant lui-même, pas sur un porteur. |
Retry-After ne part que sur un refus : c'est un en-tête de refus, et sur une réponse qui a réussi il se lirait comme un ordre d'attendre. Pas de X-RateLimit-Reset non plus : le limiteur ne connaît l'instant de remise à zéro qu'au refus, et un Reset approximatif ferait dormir un client à côté. Remaining vaut ce qu'il valait au passage de la garde — le jeton de la requête en cours est déjà décompté. Seule exception : la vérification de certificat est publiquement mise en cache, donc elle omet Remaining, qui appartient à un appelant et non à un cache.
Le budget de chaque appel
Chaque opération déclare le temps qu'elle s'autorise. Règle le timeout de ton client au moins dessus : /generate, /verify et /certify prennent jusqu'à 60 s, les lectures 10 à 15. Ces réponses ne sont pas streamées : rien n'arrive avant la fin, un client qui coupe à 30 s perd une génération déjà payée. Le budget de chaque opération est dans la spécification (x-kaneme-timeout-seconds), avec les plafonds ci-dessus (x-kaneme-rate-limits).