Appeler proprement

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.

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).

Le nombre de voix

1 voix incluse en Gratuit ; 2 par siège payant. Une voix supplémentaire coûte 5 crédits ; en Gratuit, elle exige un premier achat. Une création refusée répond 402 voice_limit_reached.

Lire une liste en entier

Chaque liste rend nextCursor. Tant qu'il n'est pas null, il reste des éléments : rappelle le même endpoint avec ?cursor=…. Nul = tu as tout vu — et cette fois c'est une information, pas une supposition. Le curseur est opaque : recopie-le, ne le fabrique pas. Un curseur illisible est refusé (400) plutôt qu'ignoré, sinon tu boucleras sur la première page en croyant avancer.

Rejouer un appel sans le payer deux fois

Ajoute Idempotency-Key: <ton identifiant> sur les écritures (/generate, /improve, /documents, /voices, /projects, /sources, /certify). Si un appel reste sans réponse, retente avec la même clé : tu récupères la réponse du premier, marquée idempotentReplay, sans second débit ni second document. Clé valable 24 h.

La même clé sur une demande différente est refusée (422) plutôt que rejouée : mieux vaut un refus lisible qu'une réponse qui ne correspond pas. Les mesures (/score, /verify, /compare) n'en prennent pas — une clé y masquerait une re-mesure volontaire.

Les codes, quand ça casse

Chaque erreur porte un code lisible en plus du statut HTTP. ⚠️ Ne pas confondre un ÉCHEC avec une abstention : celle-ci répond 200, avec probability: null.