Limites de débit

Comportement de la limitation de débit

L'API applique des limites d'usage pour protéger la stabilité et l'équité. Quand les limites sont dépassées, l'API répond avec 429 et inclut des indications de retry.

Comportement des en-têtes (exact)

Cas	En-têtes retournés
Réponses authentifiées normales (2xx/4xx comme 422)	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
`429 rate_limit_exceeded` (quota quotidien/mensuel)	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `Retry-After`
`429 rps_limit_exceeded` / `429 abuse_penalty_active`	`Retry-After` (les champs JSON propres au RPS sont dans le corps)
Réponse idempotente rejouée	`Idempotency-Replayed: true`

Types d'erreurs 429

error	Signification	Action à effectuer
rps_limit_exceeded	Le débit de requêtes par seconde est dépassé.	Attendez `Retry-After` et réessayez avec délai aléatoire. Le JSON inclut `retry_after_ms`, `backoff_hint`, `tier_rps_limit`, `penalty_active`.
abuse_penalty_active	Une fenêtre de pénalité temporaire est active après des rafales répétées.	Ne lancez pas de nouvelles tentatives en boucle; attendez toute la fenêtre de pénalité.
rate_limit_exceeded	Le quota du plan/jour/mois est atteint.	Attendez la réinitialisation ou passez à une offre supérieure.
idempotency_key_reused	La même `Idempotency-Key` a été réutilisée avec une méthode, un chemin, une query ou un corps différent.	Générez une nouvelle clé pour la nouvelle opération. Le statut HTTP est `409`.
request_in_progress	Une requête correspondante avec la même clé est encore en cours.	Attendez `Retry-After` et réessayez avec la même clé. Le statut HTTP est `409`.

Nouvelles tentatives sûres avec Idempotency-Key

Les requêtes astrologiques POST authentifiées et facturables acceptent l'en-tête optionnel Idempotency-Key: <client-generated unique operation key>. Utilisez-le quand vous réessayez une requête qui a peut-être expiré après avoir atteint l'API.

Même méthode, chemin, query string, corps et clé retournent la première réponse terminée avec Idempotency-Replayed: true. Les requêtes rejouées ne relancent pas le calcul et ne consomment pas de quota supplémentaire.

Les clés sont conservées environ 24 heures. Les requêtes sans cet en-tête gardent le comportement existant inchangé.

Stratégie de nouvelle tentative client recommandée

Respectez toujours Retry-After s'il est présent.
Utilisez un délai exponentiel avec délai aléatoire complet.
Délai de base : 250ms, délai maximum : 5s.
Pour les nouvelles tentatives POST facturables, réutilisez la même Idempotency-Key uniquement pour exactement la même requête.
Définissez un plafond de tentatives pour éviter les boucles infinies.

Notes importantes

Ne réessayez pas immédiatement en boucle serrée après un 429.
Des pics répétés peuvent déclencher des fenêtres de blocage temporaires.
Les limites côté serveur sont appliquées même si une limitation côté client existe.

Référence

Base URL : https://api.freeastroapi.com

Cette page est la cible retournée par les réponses de limitation dans le champ docs.