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 — tu ne paies 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.
• Pré-réservation. Les crédits sont réservés/débités au dispatch du job — pas après son achèvement. Cela évite les race-conditions, mais signifie aussi : un job interrompu ne rend pas automatiquement les crédits.

Mécanique des crédits

Côté Laravel, devant chaque endpoint payant se trouve le middleware credits:N. Il vérifie la balance de l'équipe, débite, puis seulement lance le contrôleur.

• Middleware credits:N → débite N crédits avant le dispatch du job. Si l'équipe descend sous N, l'API répond directement 402 Insufficient Credits sans dispatch.
• 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) sont déjà payés dès la réponse. Le worker en arrière-plan hérite de la facturation ; un crash du worker ne rembourse pas automatiquement.

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/settings/api-documentation.

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. Tu peux 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érifie toujours via GET si le premier job tourne déjà (status == processing). Sinon tu paies double.
• Utilise include= là où c'est supporté — économise des roundtrips et du quota chez les fournisseurs tiers.

Continuer avec API Projets · retour à Authentification.