Crédits et limites

AstroWay utilise un modèle de crédits au lieu d’un simple compteur de requêtes.

Obtiens une clé API en 60 secondes

aw_test_demo_aaaa1111

S'inscrire - gratuit→

C’est plus juste : les endpoints légers (/planets) coûtent 10 crédits, les lourds (/rectification) - 500.

Deux types de limites

1. Budget de crédits journalier/mensuel

Le nombre de crédits par mois dépend du plan :

Plan	Crédits/mois	Limite journalière
Free	10 000	~333
Indie	50 000	~1 667
Starter	200 000	~6 667
Pro	800 000	~26 667
Business	3 500 000	~116 666
Enterprise	Custom	Custom

Dès que les crédits sont épuisés, les requêtes suivantes renvoient 402 Payment Required (Free) ou déclenchent la facturation overage (Indie+).

2. Limite de débit (requêtes par minute)

Plan	RPM
Free	10 req/min
Indie	30 req/min
Starter	120 req/min
Pro	400 req/min
Business	1 000 req/min
Enterprise	Custom

La limite de débit est une fenêtre glissante. Si tu as envoyé 120 requêtes en 10 secondes, les 50 secondes suivantes sur cette clé renverront 429.

Astuce

La limite de débit et le budget de crédits sont indépendants. Tu peux avoir des crédits, mais ne pas passer la limite de débit. Et vice versa.

Si une clé a une liste d’origines autorisées, chaque entrée de la liste reçoit sa part de cette limite : la limite de la clé est divisée par le nombre d’entrées, arrondie à l’unité supérieure. Un site avec un widget intégré ne peut pas, de ce fait, consommer le quota payé par le propriétaire de la clé, laissant ses autres domaines opérationnels. La limite globale de la clé n’augmente pas : les parts la divisent, elles ne s’y ajoutent pas.

Le compteur est géré par entrée, et non par l’hôte d’origine. L’entrée *.example.com correspond à un seul compteur pour tous les sous-domaines, sinon la restriction serait contournée en inventant un nouveau sous-domaine pour chaque requête. Quand il n’y a qu’une seule entrée dans la liste, la part est égale à la limite et rien ne change.

3. Endpoints publics (sans clé)

14 dictionnaires de référence /v1/reference/* (signs, planets, houses, aspects, elements, modalities, polarities, dignities, decans, nakshatras, lots, asteroids, zodiac-systems, glyphs) sont servis publiquement, sans X-Api-Key et coûtent 0 crédits. La limite est de 30 requêtes / heure par IP. Ces mêmes données sont exposées en tant que ressources MCP astroway://reference/<slug> pour les agents LLM.

La même limite s’applique au reste des namespaces publics : /v1/public/*, /v1/embed/*, /v1/i18n/*.

Quota pour le rendu côté serveur

30 requêtes par heure sont calculées pour le navigateur : chaque visiteur apporte sa propre IP et son propre quota. Si les requêtes sont faites par ton serveur (plugin WordPress, SSR, préchauffage du cache), une seule adresse agit pour tous les visiteurs et épuise la limite en quelques rechargements de page.

Pour ce cas, envoie l’en-tête X-AstroWay-Site-URL avec l’adresse du site :

X-AstroWay-Site-URL: https://example.com/

Mode	Limite
Sans en-tête	30 requêtes / heure par IP ; les widgets /v1/embed/* ont une limite séparée de 120 / heure par IP
Avec en-tête	300 requêtes / heure par site, plafond de 600 / heure par IP

L’en-tête est autorisé en CORS et n’est pas une information d’identification, donc le plafond par IP reste : quel que soit le nombre de domaines nommés à partir d’une seule adresse, le total ne dépassera pas 600 requêtes par heure. Les deux compteurs sont nécessaires simultanément : le compteur de site s’active lorsqu’un site accède à partir de plusieurs adresses (CDN, équilibreur de charge), le compteur IP s’active lorsque de nombreux noms proviennent d’une seule adresse.

Un appel n’est pas toujours une unité. Un endpoint public lourd consomme plus du même panier, au lieu d’en obtenir un séparé. POST /v1/public/synastry coûte 3, car il s’agit de deux cartes et d’une matrice d’aspects de 45 cellules : le plafond pratique pour celui-ci est de 10 par heure depuis une adresse non déclarée, 100 pour un site déclaré et 200 par adresse. Tout le reste coûte 1. Quand un appel coûte plus d’une unité, la réponse l’indique dans l’en-tête X-RateLimit-Cost, et un appel qui coûte plus que ce qu’il reste dans le panier est rejeté, et non mis en négatif.

L’en-tête de réponse X-RateLimit-Scope (ip ou site) indique quel compteur est actuellement le plus restrictif. Les autres en-têtes X-RateLimit-* décrivent uniquement celui-ci, c’est-à-dire un seul des deux compteurs. Le second est visible dans X-RateLimit-Counters :

X-RateLimit-Scope: site
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Counters: ip=597/600, site=297/300

Le format est scope=restant/limite séparé par une virgule. L’en-tête n’apparaît que lorsque deux compteurs sont réellement présents : un appel anonyme avec X-AstroWay-Site-URL. Un appel avec une clé payante est comptabilisé selon ta clé et ton tarif, il n’y a qu’un seul compteur et pas d’en-tête. Lis-le si tu rends depuis le serveur plusieurs domaines à partir d’une seule adresse : le panier du site est propre à chaque domaine, mais le plafond IP est partagé, et c’est lui qui est atteint en premier.

Mets en cache les réponses de ton côté : l’horoscope quotidien ne change pas pendant la journée, et un cache jusqu’à minuit résout complètement la question de la limite.

Clé payante sur les endpoints publics. /v1/public/* et /v1/embed/* fonctionnent sans clé, mais si tu la transmets (X-Api-Key), la requête est comptabilisée selon ton tarif, et non selon le quota anonyme, et la réponse n’aura pas de filigrane gratuit. Cela a du sens pour le rendu côté serveur : une seule machine agit pour tous les visiteurs, et les 300/heure anonymes sont insuffisants pour elle.

Tableau des coûts

Un tableau complet et transparent avec tous les 771+ endpoints et leurs coûts est disponible sur la page Coût des endpoints. DivineAPI/AstrologyAPI/Prokerala ne publient pas un tel tableau. Voici un aperçu rapide :

Tier	Crédits	Temps typique	Exemples
1	10	< 50 ms	/planets, /moon-voc, /iching
2	20	50–200 ms	/chart, /harmonics, /horary
3	50	200–500 ms	/synastry, /progressions, /acg
4	100	> 500 ms	/transit-calendar, /forecast-calendar
5	250	quelques s	/rectification/trutine
6	500	jusqu’à 120 s	/rectification

En-têtes de réponse

Chaque réponse contient :

X-Credits-Used: 20
X-Credits-Remaining: 9980
X-Credits-Limit: 10000
X-Credits-Reset: 2026-05-01T00:00:00Z
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1714521600
X-RateLimit-Origin-Limit: 60
X-RateLimit-Origin-Remaining: 59
X-Request-Id: 8aec43e9bc749b37e998a489bbad1757

• X-Credits-Used : combien a été débité pour cette requête
• X-Credits-Remaining : solde du budget mensuel
• X-Credits-Limit : budget total de crédits par mois (selon le plan)
• X-Credits-Reset : date ISO-8601 de la réinitialisation du solde
• X-RateLimit-* : état actuel de la fenêtre glissante (format standard)
  • X-RateLimit-Scope : quel compteur est actuellement le plus restrictif : ip, site ou key. La valeur key signifie que la requête a été comptabilisée selon ta clé et la limite de ton tarif, et non selon le quota anonyme.
  • X-RateLimit-Counters : sur un endpoint public, appelé avec X-AstroWay-Site-URL, tous les compteurs par lesquels la requête a été comptabilisée, au format scope=restant/limite. Les en-têtes ci-dessus ne décrivent que le plus restrictif.
  • X-RateLimit-Reset : le moment où la requête la plus ancienne tombera de la fenêtre, c’est-à-dire quand un slot se libérera. Ce n’est pas le moment de l’ouverture complète du bucket : après cela, une requête passera, et Reset se déplacera vers la suivante dans le temps. Un client qui attend jusqu’à Reset puis envoie un lot recevra à nouveau 429, il est donc plus fiable d’envoyer une requête à la fois ou de mettre en cache les réponses de ton côté.
  • Une requête rejetée (429) ne consomme pas de quota et ne décale pas la fenêtre : le compteur n’est réapprovisionné que par les requêtes réussies.
  • X-RateLimit-Origin-Limit et X-RateLimit-Origin-Remaining : n’apparaissent que lorsque la requête a été traitée selon une entrée de la liste des origines autorisées, et indiquent la part allouée spécifiquement à cette entrée. Un refus dû à cette part est également un 429, et le texte indique quelle entrée est épuisée.
• X-Subscription-Status et X-Subscription-Grace-Ends : n’apparaissent que lorsque la période payée est déjà terminée, et que la période de grâce de 3 jours est toujours en cours (X-Subscription-Status: grace). Les requêtes sont traitées selon ton tarif jusqu’au moment indiqué dans X-Subscription-Grace-Ends, après quoi la réponse est 402 SUBSCRIPTION_EXPIRED. Si ton client logue les en-têtes, c’est le signal le plus précoce qu’il est temps de renouveler le plan.
• X-Request-Id : identifiant de la requête, 32 caractères hexadécimaux ; mentionne-le lors de la prise de contact avec le support.

Combien a déjà été dépensé : trois méthodes

Tu peux vérifier le solde actuel de tes crédits de trois manières – de la plus rapide à la plus détaillée :

1. Dans chaque réponse : les en-têtes X-Credits-Remaining / X-Credits-Used / X-Credits-Limit sont renvoyés pour toute requête (même en cas d’erreur). Tu n’as rien à appeler en plus – le solde est toujours sous tes yeux.
2. Par une requête séparée : GET /v1/keys/usage avec ta X-Api-Key renvoie les credits (used / remaining / limit / reset), l’usage (requêtes pour today / week / month) et les 20 principaux endpoints sur 30 jours. Un seul appel, sans clé admin séparée.
3. Dans le tableau de bord : api.astroway.info/dashboard/billing affiche le solde, le graphique d’utilisation et la répartition par endpoint en temps réel.

curl https://api.astroway.info/v1/keys/usage \
  -H "X-Api-Key: $AW_KEY"

Astuce

Contrairement à la plupart des API (Anthropic, OpenAI), AstroWay renvoie le solde restant directement dans l’en-tête de chaque réponse (X-Credits-Remaining) – tu n’as pas besoin d’aller dans le tableau de bord ou une API d’utilisation séparée pour savoir combien il te reste.

Mise en cache

Les requêtes identiques dans les 5 minutes sont renvoyées depuis le cache sans débit de crédits. C’est un en-tête séparé :

X-Cache: HIT
X-Credits-Used: 0

Ce qui est considéré comme “identique” :

• Le même endpoint
• Le même corps JSON (octet par octet après normalisation des espaces)
• La même clé API

C’est sûr, car tous les endpoints sont déterministes – une entrée identique donne toujours une sortie identique.

Streaming et webhooks

Streaming (/stream/*)

10 endpoints de streaming sont facturés comme Tier 1 : 10 crédits par appel. Chaque appel recalcule les positions des planètes, il s’agit donc d’un calcul complet et non d’une recherche en cache – il n’y a pas de tarif “moins cher” séparé par tick.

Chaque réponse contient deux champs pour un polling économique :

• tickSeconds : intervalle de polling recommandé ;
• nextEventAt : quand l’état changera la prochaine fois.

Poller plus fréquemment que tickSeconds est une perte de crédits : l’état ne changera pas avant nextEventAt.

Attention

Exemple de budget : un stream, interrogé toutes les 60 s = 1 440 appels/jour × 10 crédits = 14 400 crédits/jour. Sur Indie (50 000/mois), cela représente ~3,5 jours d’un seul stream. Pour un streaming continu – Starter+.

Webhooks (/webhooks/*)

Les opérations CRUD de gestion d’abonnement (/webhooks/subscribe, liste, affichage, suppression, /test) coûtent Tier 1 : 10 crédits chacune. Ce sont des appels rares.

La livraison d’événements (serveur → ton URL) n’est pas facturée : les crédits ne sont débités que pour les appels CRUD de gestion. 12 types d’événements sont pris en charge (report-ready, transit-alert, eclipse-alert, dasha-change, sign-ingress, etc.).

Les webhooks sont disponibles à partir du plan Pro et supérieur.

Que faire en cas de dépassement des limites

402 Payment Required : crédits épuisés

{
  "error": {
    "code": "credits_exhausted",
    "message": "Monthly credit budget exhausted. Upgrade plan or wait for reset.",
    "credits_remaining": 0,
    "credits_reset": "2026-05-01T00:00:00Z",
    "upgrade_url": "https://api.astroway.info/dashboard/billing"
  }
}

Options :

• Mise à niveau du plan : tu reçois immédiatement un nouveau budget
• Overage (Starter/Pro) : s’active automatiquement, sauf si désactivé dans les paramètres
• Attendre la réinitialisation (Free) : le 1er du mois suivant

429 Too Many Requests : RPM dépassé

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after 12 seconds.",
    "retry_after_seconds": 12
  }
}

L’en-tête Retry-After: 12 est un en-tête HTTP standard, ton client HTTP doit le comprendre.

Gestion correcte :

async function callWithRetry(endpoint: string, body: object) {
  const response = await fetch(endpoint, {
    method: 'POST',
    headers: { 'X-Api-Key': key, 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });

  if (response.status === 429) {
    const retryAfter = Number(response.headers.get('Retry-After') ?? 1);
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    return callWithRetry(endpoint, body);
  }

  return response.json();
}

Attention

Ne fais pas de backoff exponentiel sans cap – Retry-After dans la réponse contient déjà le chiffre exact. Fais-lui confiance.

Estimation du budget à l’avance

Avant l’intégration, estime combien de crédits tu auras besoin par mois :

monthly_credits = daily_active_users × calls_per_user × avg_cost_per_call × 30

Exemple : une application avec 500 DAU, chaque utilisateur effectue 3 calculs de cartes + 1 synastrie par jour :

500 × (3 × 20 + 1 × 50) × 30 = 500 × 110 × 30 = 1,650,000 credits/mo
→ Enterprise (custom)

Le calculateur de budget est sur la page Tarifs.

Suite

• Erreurs : référence complète des codes d’erreur
• Idempotence : comment effectuer des requêtes répétées en toute sécurité