Lire les en-têtes de crédits : auditer chaque débit depuis la réponse
Ce que vous allez construire : un fin wrapper client qui journalise le coût de chaque appel et ce qu'il vous reste, pour que vos propres logs deviennent la piste d'audit de facturation.
| Section | Fondamentaux de l'API |
|---|---|
| Actions utilisées | POST /v1/data/contacts/verify-email |
| Crédits | 1 (pire cas) |
| Compatible clé de test | Oui — tourne sur qk_test_ pour zéro crédit |
| Temps nécessaire | ~5 min |
| Prérequis | Une clé et n'importe quel client HTTP permettant de lire les en-têtes de réponse. |
Trois en-têtes sur chaque appel de données
X-Credits-Charged est ce que cet appel a coûté. X-Credits-Balance est ce qu'il reste ensuite. X-Price-Book identifie le barème selon lequel le débit a été calculé, de sorte qu'un devis et un débit se rattachent toujours aux mêmes règles.
curl -i -X POST https://api.qannasapi.com/v1/data/contacts/verify-email \
-H "Authorization: Bearer $QANNAS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "jane@acme.example"}'
# < HTTP/1.1 200 OK
# < X-Credits-Charged: 1 # what this call cost
# < X-Credits-Balance: 94 # what is left afterwards
# < X-Price-Book: public # which rules were appliedJournalisez le débit, pas l'estimation
Enveloppez votre client HTTP une fois et enregistrez les trois en-têtes à côté de request_id. Vous obtenez l'attribution des coûts par appel sans interroger un endpoint d'usage, et request_id est ce que le support demandera si un débit paraît anormal.
export async function call(action: string, body: unknown) {
const res = await fetch(`${API}/v1/data/${action}`, {
method: "POST",
headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
body: JSON.stringify(body),
});
const json = await res.json();
// Your logs become the billing audit trail.
logger.info("qannas.call", {
action,
request_id: json.request_id,
charged: Number(res.headers.get("X-Credits-Charged")),
balance: Number(res.headers.get("X-Credits-Balance")),
});
return json;
}Surveillez le solde, pas l'horloge
Comme le solde revient à chaque appel, vous pouvez limiter le débit ou alerter à partir de la réponse que vous avez déjà. Aucun endpoint de quota à interroger et aucun décalage entre dépenser et le savoir.
// The balance arrives on the call you already made —
// there is no quota endpoint to poll and no lag.
const balance = Number(res.headers.get("X-Credits-Balance"));
if (balance < LOW_WATER_MARK) {
pauseNonUrgentJobs();
alertOps(`credits low: ${balance}`);
}Résumé
| Motif | Comment |
|---|---|
| Ce que cet appel a coûté | X-Credits-Charged |
| Ce qu'il reste | X-Credits-Balance |
| Quelles règles s'appliquaient | X-Price-Book |
| Tracer un débit | request_id dans le corps de la réponse |
| Limiter le débit | Alertez sur X-Credits-Balance de l'appel que vous venez de faire |
Checklist de mise en production
- Journalisez X-Credits-Charged, X-Credits-Balance et request_id à chaque appel.
- Alertez sur l'en-tête de solde plutôt que d'interroger un endpoint d'usage.
- Conservez request_id — c'est ainsi qu'un débit précis se retrouve.
- Attendez-vous à X-Credits-Charged: 0 sur un résultat vide et n'y voyez pas un échec.
Étapes suivantes
Lancez d'abord l'estimation. Elle ne coûte rien et applique exactement le même calcul que le compteur.