Crédits & rate-limits

Rankion facture les actions API payantes via un système de crédits simple. Les endpoints purement en lecture (listes GET, polls de statut, vues détail) sont toujours gratuits — vous ne payez que ce qui consomme des tokens, des API externes ou du temps GPU.

Que sont les crédits ?

• Une unité unique sur toute la plateforme. Que ce soit la génération d'article, un run AI Visibility, un pull de backlinks ou un edit d'image — tout est facturé en crédits.
• Balance d'équipe. Les crédits sont rattachés à l'équipe, pas à l'utilisateur. Tous les tokens d'une même équipe puisent dans le même pot.
• Le moment du débit dépend de l'endpoint. Certains endpoints débitent avec la réponse réussie, d'autres dans le job ou à sa fin. Si un job échoue, les crédits ne reviennent que là où l'endpoint prévoit un remboursement.

Mécanique des crédits

Devant les endpoints payants se trouve l'un de deux middlewares, et un seul des deux débite.

• credits:N → vérifie seulement la balance. Si l'équipe est sous N, l'API répond 402 Insufficient Credits et aucun job ne démarre. Le débit vient plus tard, dans le contrôleur ou le job.
• credits-auto:N → même vérification, puis débite N crédits dès que la réponse est un 2xx. 4xx et 5xx ne coûtent rien.
• Refreshs inline (par ex. Keyword Explorer avec ?cache=false) consomment forfaitairement 50 crédits directement — le cache-bust est l'opération coûteuse.
• Jobs async (HTTP 202) : avec credits-auto:N, le débit est fait dès la réponse. Avec credits:N, le job débite lui-même. Un crash du worker ne rembourse que là où l'endpoint le prévoit ; POST /v1/google/gsc/properties/{p}/sync ne rembourse pas.

Coûts en crédits (sélection)

Liste complète : docs/API_REFERENCE.md — les 137 endpoints avec colonne crédits. Tableau live : rankion.ai/api-docs.

Crédits insuffisants — HTTP 402

Si la balance de l'équipe ne suffit pas pour l'action, l'API répond 402 Payment Required :

{
  "message": "Insufficient credits",
  "error": "insufficient_credits",
  "required": 10,
  "available": 4
}

Le job n'est pas dispatché, l'appelant peut informer l'utilisateur ou recharger des crédits. Vous pouvez récupérer la balance courante à tout moment via l'API crédits.

API crédits

# Balance courante + infos de plan
curl -H "Authorization: Bearer $TOKEN" "$BASE/credits"

# Historique de facturation (paginé)
curl -H "Authorization: Bearer $TOKEN" "$BASE/credits/history"

Exemple de réponse pour GET /v1/credits :

{
  "data": {
    "balance": 1240,
    "plan": "growth",
    "monthly_allotment": 5000,
    "renews_at": "2026-05-15T00:00:00Z"
  }
}

GET /v1/credits/history renvoie par entrée : created_at, delta (négatif = consommation, positif = top-up), endpoint, reference_id (par ex. l'ID de l'article), balance_after. Cela permet d'attribuer précisément quelle action a consommé quels crédits.

Rate-limits

En complément du système de crédits, il existe une limite de requêtes classique par token :

• ~60 requêtes par minute par token par défaut pour les routes auth:sanctum.
• Si le client dépasse la limite, l'API répond 429 Too Many Requests avec un header Retry-After.
• Les boucles de polling sur des jobs async ne doivent donc jamais être plus agressives que toutes les 5 secondes — et toujours avec backoff exponentiel sur 429.

Certains endpoints ont des limites plus strictes, par ex. :

• POST /v1/tracking-projects/{id}/generate-report → 1 requête / 30 min / projet. Sinon 429 {error: "rate_limited"}.
• Public Share-Unlock (POST /share/{token}/unlock) → 5 / minute (protection brute-force).

Conseils pour économiser

• Utiliser le cache. Explorer et endpoints similaires cachent 60 min — ?cache=false uniquement si des données fraîches sont vraiment nécessaires.
• Polling async avant un nouveau dispatch. Avant un second POST /generate, vérifiez toujours via GET si le premier job tourne déjà (status == processing). Sinon vous payez double.
• Utilisez include= là où c'est supporté — économise des roundtrips et du quota chez les fournisseurs tiers.

Continuer avec API Projets · retour à Authentification.