Pièges à connaître
Le comportement réel de l’API aux endroits où le code généré se trompe d’habitude. Chaque point ci-dessous décrit la façon dont le serveur traite la requête, pas une préférence de style.
Requêtes
- La barre oblique finale est obligatoire.
/api/astro/tithi/fonctionne ;/api/astro/tithirépond 301, et un client qui suit la redirection renvoie la requête en GET, sans le corps. - Une même valeur porte des noms de champ différents selon l’endpoint. L’instant s’appelle
date_timepresque partout, maisdatetimesur/api/astro/chart/et les cartes divisionnaires ; le décalage est en généraltimezone_as_float, maistimezone,tzoutime_zonesur certains ; le nœud lunaire estrahu,nodeounode_type, avec des valeurs par défaut différentes. Construisez chaque corps à partir de la liste des champs de l’endpoint, au lieu de réutiliser partout le même. - La longitude est négative à l’ouest de Greenwich, et la latitude négative au sud de l’équateur. New York, c’est
-74.006, pas74.006. - Les limites de latitude varient : la plupart des endpoints de thème et de panchang acceptent jusqu’à ±89,9, les endpoints Prashna Ashtamangala et Jamakkol jusqu’à ±66. Une valeur hors de la plage de l’endpoint est rejetée avec une erreur 400.
Entrées erronées qui renvoient quand même 200
- Un
date_timesans décalage n’est pas lu comme l’heure locale du lieu : la plupart des endpoints le prennent en UTC+05:30, quelques-uns en UTC. La réponse est un 200 normal, mais pour un autre instant — parfois la veille. Envoyez toujours un décalage ou un Z. timezone_as_floatn’est pas comparé au décalage dedate_time. S’ils ne concordent pas, vous obtenez un 200 pour le mauvais instant. Utilisez le décalage en vigueur à cette date (heure d’été comprise), pas celui d’aujourd’hui ;/api/astro/date_time/le déduit des coordonnées.- Quelques champs basculent sur une valeur de repli au lieu d’échouer : sur
/api/astro/chart/, toute valeur deascendant_posautre questartouenddésigne la cuspide de la maison, et sur/api/astro/festival/, toute valeur demoon_optionautre quepoornimase comporte commeamavas. Une faute de frappe y change la réponse sans la moindre erreur.
Clés
- Sur un endpoint doté d’une table des clés, une clé qui n’y figure pas fait rejeter toute la requête avec une erreur 400, et le message nomme les clés non reconnues. Rien n’est calculé, rien n’est facturé.
- Les noms de clés sont exacts, et parfois surprenants :
/api/astro/panchanga/utiliseyogampour le yoga du jour,rahu_kaalametcalcualte_special_tithi(avec cette orthographe). Copiez-les depuis la table des clés au lieu de les deviner. - Une clé qui exige un champ supplémentaire échoue avec une erreur 400 si ce champ manque, par exemple la clé
phone_numberde/api/astro/numerology/sans valeurphone_number. - Un appel réussi coûte un crédit, quel que soit le nombre de clés demandées. Demandez tout ce dont vous avez besoin en un seul appel —
tithi,vaara,yogametkaranaensemble — plutôt qu’un appel par clé. - Les endpoints à usage unique comme
/api/astro/tithi/et/api/astro/rahu-kaal/n’ont pas de table des clés : ils renvoient toujours le même ensemble fixe, et un tableaukeysqui leur est envoyé est ignoré. - Sur
/api/astro/numerology/, les clés valides dépendent desystem. Une clé appartenant à un autre système renvoie une erreur 400 qui la nomme.
Crédits, erreurs et limites
- La plupart des endpoints coûtent un crédit par appel réussi.
/api/astro/chat/,/api/astro/pdf/horoscope/et/api/astro/pdf/yearbook/coûtent 25 crédits chacun : tenez-les à l’écart des boucles et des nouvelles tentatives. - Les appels en échec sont gratuits : les crédits sont réservés avant le calcul et restitués pour toute réponse hors 2xx, qui contient alors
X-Credits-Charged: 0. - Les réponses facturées contiennent
X-Credits-Cost,X-Credits-ChargedetX-Credits-Remaining, ainsi queX-RateLimit-LimitetX-RateLimit-Remainingpour la limite par minute. Lisez-les au lieu de tenir vous-même le compte du solde. - Un solde épuisé renvoie 402, avec
insufficient_creditsdansmessage; sondatafournitcost_credits,credits_remainingetrecharge_url. Réessayer ne sert à rien tant que la formule n’a pas été relevée ou que son quota n’a pas été remis à zéro. - Au-delà de la limite par minute, l’API renvoie 429, avec
api_key_rate_limiteddansmessageet un en-têteRetry-After(ainsi queretry_after_secondsdansdata). Attendez ce délai avant de réessayer. - Une clé mal formée, révoquée ou expirée renvoie 401
invalid_api_key. Une route, une portée ou une adresse IP que votre clé n’a pas le droit d’utiliser renvoie 403endpoint_not_allowed,scope_not_allowedouip_not_allowed. - Les erreurs des contrôles de clé et de crédits ont la forme
{ "error": "…", "message": "insufficient_credits", "is_error": true, "data": { … } }: basez votre logique sur le code contenu dansmessage. En cas d’échec, les réponses de calcul utilisent l’enveloppe{ "data": {}, "status": 400, "is_error": true, "message": "…" }, avec la raison en clair dansmessage. Les deux contiennentis_error. - Les deux endpoints PDF renvoient le PDF lui-même (
application/pdf), pas du JSON. Écrivez le corps dans un fichier ; il n’y a aucun lien de téléchargement à récupérer ensuite.
Astrologie
- Les endpoints védiques sont sidéraux et appliquent la correction d’ayanamsa côté serveur ; les routes
/api/astro/western/sont tropicales par défaut. Ne soustrayez pas vous-même un ayanamsa du résultat. /api/astro/kp-chart/utilise les cuspides Placidus dans le zodiaque sidéral : ses positions en maisons peuvent donc différer de celles de/api/astro/chart/pour la même naissance. C’est la méthode KP, pas une incohérence.- Le rashifal est une prévision par signe, sans thème natal : envoyez
rashiavec le nom anglais du signe, par exempleleo, et non des données de naissance. - Les tirages de tarot sont aléatoires, sauf si vous envoyez
seed. Chaque réponse renvoie la graine utilisée : conservez-la si un tirage doit pouvoir être réaffiché à l’identique. /api/astro/numerology/iching/associe numériquement une date et un nom aux 64 hexagrammes. Aucun tirage n’a lieu : il n’y a donc ni traits mutants ni second hexagramme.