Clés et crédits

Un crédit paie un appel. Cette page dit ce qui coûte un crédit, ce qui ne coûte rien, d'où viennent tes crédits et où suivre ta consommation.

Ce qui coûte un crédit

Chaque appel facturé coûte un crédit : une lecture comme GET /students, ou une opération appelée avec POST /operations/<nom>. Le crédit est débité avant que l'appel s'exécute. L'API et le MCP puisent dans les mêmes crédits.

Un appel qui échoue peut coûter un crédit. Un 400 ou un 404 est facturé quand l'appel est arrivé jusqu'à tes données :

• un paramètre refusé sur une liste, comme limit=500 (400 VALIDATION) ;
• un identifiant introuvable ou qui n'est pas le tien (404 NOT_FOUND) ;
• une opération qui s'est lancée, puis refuse elle-même la demande (400 VALIDATION).

Une requête que l'API refuse avant de l'exécuter ne coûte rien : un nom d'opération inconnu (404 OPERATION_NOT_EXPOSED), un périmètre manquant (403), un dry_run sur une opération qui n'a pas d'aperçu (400 DRY_RUN_UNSUPPORTED), ou un corps invalide. Sur une opération, un argument que son schéma refuse, comme un champ manquant ou d'un mauvais type, est remboursé (400 VALIDATION). Le refus de l'opération elle-même reste facturé.

Ce qui est gratuit ou remboursé

• GET /me, GET /openapi.json, GET /operations et GET /events. GET /openapi.json et GET /operations se lisent même sans clé.
• Un aperçu avec dry_run: true, pour une opération qui sait en faire un.
• Un rejeu avec la même Idempotency-Key (Idempotency-Replayed: true).
• Les erreurs 409 (IDEMPOTENCY_MISMATCH, CONFLICT), 401, 402, 403 et 429.
• Une réponse 5xx sur une lecture, et une lecture interrompue avant la fin.

D'où viennent tes crédits

1. Les crédits inclus. Ton offre en donne un certain nombre chaque mois : tu le vois dans l'app. Ils servent en premier. À la remise à zéro, ils repartent au niveau de ton offre, et ceux que tu n'as pas utilisés ne s'ajoutent pas au mois suivant. La date est dans credits.plan_resets_at, dans l'en-tête X-Credits-Plan-Resets-At et dans l'app.
2. La réserve. Ce sont les crédits achetés en packs ou accordés. Ils ne périment jamais, et ne servent qu'une fois tes crédits inclus consommés. Seul le propriétaire de l'équipe achète des packs.

Quand il ne reste plus rien, les appels facturés reçoivent un 402 CREDITS_EXHAUSTED, qui ne coûte rien. Ils reprennent à la remise à zéro, ou dès qu'un pack est ajouté.

Où suivre ta consommation

Dans l'app, ouvre Paramètres › Intégrations › Clés API :

• l'onglet Clés affiche, au-dessus de la liste, les crédits qu'il te reste, les appels du mois, la date de remise à zéro et ta réserve ;
• l'onglet Crédits & packs détaille les mouvements, comme l'allocation mensuelle, les achats et les remboursements, et propose les packs ;
• l'onglet Journal des appels liste les appels qui arrivent à l'étape des crédits (facturés, remboursés, aperçus et rejeux) avec leur clé, leur opération, leur statut et leur crédit. GET /me et les refus qui tombent avant, comme un 401, un 403 ou un 429, n'y laissent pas de ligne.

Par l'API, GET /me donne ton solde gratuitement, et X-Credits-Remaining te suit à chaque appel facturé.

Dépenser moins

• Demande limit=200 sur les listes : une page coûte un crédit, quel que soit son nombre d'objets.
• Relis seulement les changements avec since, au lieu de tout relire.
• Garde la même Idempotency-Key pour chaque nouvel essai d'une même écriture : le rejeu est gratuit.
• Crée une clé par outil : le journal te montre alors lequel consomme.

Le script de la page Écrire un script applique ces règles. Pour lire les en-têtes de crédits sur un vrai appel, reviens à Premier appel.