Authentification
Un en-tête, une clé, et quelques erreurs qui ont chacune un sens précis.
L’en-tête
Envoyez votre clé dans X-API-Key à chaque requête. Pas de flux OAuth, pas d’échange de jeton, rien à rafraîchir.
curl -X POST https://api.occultapi.com/api/astro/tithi/ \
-H "X-API-Key: yt_live_a1b2c3d4_x9K2mQ7vB4nR8sL1wY6tZ3pC5hJ0dF" \
-H "Content-Type: application/json" \
-d '{ "date_time": "2026-09-16T06:00:00+05:30", "latitude": 26.9124, "longitude": 75.7873, "timezone_as_float": 5.5 }'Format des clés
Une clé ressemble à yt_live_a1b2c3d4_x9K2mQ7vB4nR8sL1wY6tZ3pC5hJ0dF : la marque, l’environnement, un préfixe public de huit caractères, puis le secret.
yt_live_…consomme de vrais crédits sur votre solde.yt_test_…sert au développement et apparaît comme tel dans votre historique d’utilisation.
Le préfixe est public et indexé exprès : si une clé fuit un jour dans un dépôt public, on peut la retrouver et la révoquer grâce à son seul préfixe, sans avoir besoin de la partie secrète.
Affichée une fois, stockée sous forme d’empreinte
Une clé ne s’affiche qu’une seule fois, à sa création. Nous n’en stockons qu’une empreinte SHA-256 : ni un administrateur ni une copie de la base de données ne peuvent la retrouver, et nous sommes donc réellement incapables de vous la renvoyer. Ensuite, seuls le préfixe et les quatre derniers caractères restent visibles, ce qui suffit pour distinguer deux clés dans une liste.
Clé perdue ? Créez-en une nouvelle et révoquez l’ancienne. C’est plus rapide que de nous écrire, et c’est de toute façon la seule chose que nous pourrions faire.
Les erreurs, et celles qui ne relèvent pas de l’authentification
Chaque erreur utilise l’enveloppe standard, avec is_error: true et un code machine stable dans message. Basez votre logique sur le code, pas sur le texte.
| Statut | message | Signification | Que faire |
|---|---|---|---|
| 401 | invalid_api_key | La clé est absente, mal formée, révoquée ou expirée. | Vérifiez que l’en-tête X-API-Key nous parvient bien. Si vous avez renouvelé la clé, déployez la nouvelle. |
| 402 | insufficient_credits | La clé est valide. Le solde est vide. | Passez à une formule supérieure ou attendez la remise à zéro mensuelle. Ce n’est pas un problème d’authentification : régénérer la clé n’y changera rien. |
| 403 | endpoint_not_allowed | Cette route n’est pas accessible avec une clé API : le chemin ou la méthode est incorrect, ou l’endpoint a été retiré. | Comparez la route et la méthode avec la référence. Ni un nouvel essai ni une nouvelle clé n’y changeront rien. |
| 403 | scope_not_allowed | La clé n’a pas la portée (scope) requise par cet endpoint. | Créez une clé avec les bonnes portées, ou laissez les portées vides pour les autoriser toutes. |
| 403 | ip_not_allowed | La clé est limitée à une liste d’IP autorisées, et la requête vient d’une adresse qui n’y figure pas. | Appelez depuis une IP autorisée, ou créez une clé avec les bonnes IP — ou sans aucune, pour tout autoriser. |
| 403 | account_suspended | Le compte est suspendu : toutes ses clés sont refusées. | Contactez le support. Régénérer la clé n’y changera rien. |
| 429 | api_key_rate_limited | Trop de requêtes en une minute pour cette clé. | Ralentissez et réessayez après le nombre de secondes indiqué dans l’en-tête Retry-After. |
| 400 | (erreurs de champ) | Le corps de la requête est incorrect. message nomme chaque champ fautif. | Lisez message : il est précis. Jamais facturé. |
Le point à retenir : 402 n’est pas un échec d’authentification. La clé est bonne, le solde est vide. Régénérer la clé est le mauvais réflexe classique, et ne change rien.
En-têtes de crédits
Chaque réponse indique ce que l’appel a coûté et ce qu’il vous reste : vous suivez vos dépenses sans requête supplémentaire.
X-Credits-Cost: 1 # what this endpoint costs
X-Credits-Charged: 1 # what you were actually billed — 0 on any error
X-Credits-Remaining: 149 # balance after this callC’est X-Credits-Charged qu’il faut journaliser. Une requête en échec affiche toujours 0 : le crédit est réservé avant le calcul et libéré si celui-ci n’aboutit pas proprement. Une intégration défaillante ne peut donc pas vider un solde pendant que vous la déboguez.
Limites de débit
Les limites s’appliquent par clé et par minute. Elles servent à contenir une clé qui aurait fuité, pas à vous rationner. Si vous en dépassez une, vous recevez un 429 avec un en-tête Retry-After en secondes : attendez ce délai au lieu de réessayer aussitôt. Les réponses contiennent aussi X-RateLimit-Limit et X-RateLimit-Remaining.
Un 429 n’est jamais facturé. Si vous atteignez la limite en fonctionnement normal, demandez-nous de la relever.
Protéger une clé
- Appelez depuis votre serveur, pas depuis le navigateur. Une clé placée dans un bundle front-end ou une application mobile est une clé publique, quel que soit son nom. N’importe qui peut la lire et dépenser votre solde.
- Conservez-la dans une variable d’environnement ou un gestionnaire de secrets. Ne la commitez jamais.
- Utilisez une clé distincte par environnement, pour pouvoir en révoquer une sans couper les autres.
- Pour renouveler une clé : créez la nouvelle, déployez-la, puis révoquez l’ancienne — dans cet ordre, pour éviter toute interruption.
- Révoquez immédiatement une clé qui a pu fuiter. La révocation est instantanée, et vos crédits restants ne sont pas touchés.
Gérez tout cela depuis votre page des clés.