ध्यान रखने की बातें

जिन जगहों पर अपने-आप बना कोड अक्सर गलत होता है, वहाँ API असल में कैसे चलता है। नीचे की हर बात यह बताती है कि सर्वर अनुरोध को कैसे सँभालता है; यह लिखने के ढंग की कोई पसंद नहीं है।

अनुरोध

आख़िरी स्लैश ज़रूरी है। /api/astro/tithi/ चलता है; /api/astro/tithi पर 301 मिलता है, और जो क्लाइंट रीडायरेक्ट पर चलता है वह अनुरोध को बिना बॉडी के GET बनाकर दोबारा भेजता है।
एक ही मान का नाम अलग-अलग एंडपॉइंट पर अलग है। समय लगभग हर जगह date_time है, पर /api/astro/chart/ और वर्ग कुंडलियों पर datetime; ऑफ़सेट आम तौर पर timezone_as_float है, पर कुछ पर timezone, tz या time_zone; राहु-केतु का फ़ील्ड rahu, node या node_type है, और सबके डिफ़ॉल्ट अलग हैं। हर जगह एक ही बॉडी चलाने के बजाय हर एंडपॉइंट की बॉडी उसकी फ़ील्ड सूची से बनाएँ।
ग्रीनविच के पश्चिम में देशांतर ऋणात्मक होता है और भूमध्य रेखा के दक्षिण में अक्षांश। न्यूयॉर्क -74.006 है, 74.006 नहीं।
अक्षांश की सीमा अलग-अलग है: ज़्यादातर कुंडली और पंचांग एंडपॉइंट ±89.9 तक लेते हैं, अष्टमंगल और जामक्कोल प्रश्न एंडपॉइंट ±66 तक। एंडपॉइंट की सीमा से बाहर का मान 400 के साथ लौटा दिया जाता है।

गलत इनपुट, फिर भी 200

बिना ऑफ़सेट वाला date_time उस जगह का स्थानीय समय नहीं माना जाता: ज़्यादातर एंडपॉइंट इसे UTC+05:30 मानते हैं, कुछ UTC। उत्तर सामान्य 200 होता है, पर किसी और पल का — कभी-कभी पिछले दिन का। हमेशा ऑफ़सेट या Z भेजें।
timezone_as_float को date_time के ऑफ़सेट से मिलाकर नहीं जाँचा जाता। दोनों अलग हों तो गलत पल का 200 उत्तर मिलता है। आज का नहीं, उस तारीख़ को लागू ऑफ़सेट लें (गर्मियों का समय भी गिनकर); /api/astro/date_time/ इसे निर्देशांकों से निकाल देता है।
कुछ फ़ील्ड विफल होने के बजाय डिफ़ॉल्ट पर चले जाते हैं: /api/astro/chart/ पर ascendant_pos में start या end के अलावा कुछ भी हो तो उसे भाव-संधि माना जाता है, और /api/astro/festival/ पर moon_option में poornima के अलावा कुछ भी हो तो वह amavas की तरह चलता है। वहाँ टाइपिंग की एक गलती बिना त्रुटि के जवाब बदल देती है।

Keys

जिस एंडपॉइंट की keys तालिका है, उस पर तालिका से बाहर की key भेजने पर पूरा अनुरोध 400 के साथ लौट आता है, और message में अनजान keys के नाम होते हैं। न कोई गणना होती है, न कोई शुल्क लगता है।
keys के नाम हूबहू होते हैं और कभी-कभी चौंकाते हैं: /api/astro/panchanga/ पर दिन के योग के लिए yogam, फिर rahu_kaalam और calcualte_special_tithi (वर्तनी यही है)। अंदाज़ा लगाने के बजाय इन्हें keys तालिका से कॉपी करें।
जिस key को एक और फ़ील्ड चाहिए, वह फ़ील्ड न होने पर 400 के साथ विफल होती है, जैसे /api/astro/numerology/ पर phone_number मान के बिना phone_number key।
एक सफल कॉल पर एक क्रेडिट लगता है, उसमें कितनी भी keys हों। जो कुछ चाहिए, एक ही कॉल में माँगें — tithi, vaara, yogam और karana एक साथ — हर key के लिए अलग कॉल नहीं।
/api/astro/tithi/ और /api/astro/rahu-kaal/ जैसे एक-काम वाले एंडपॉइंट की कोई keys तालिका नहीं है: वे हमेशा वही तय नतीजे लौटाते हैं, और उन्हें भेजी गई keys सूची इस्तेमाल नहीं होती।
/api/astro/numerology/ पर मान्य keys system पर निर्भर करती हैं। किसी दूसरी पद्धति की key भेजने पर 400 मिलता है, जिसमें उस key का नाम होता है।

क्रेडिट, त्रुटियाँ और सीमाएँ

ज़्यादातर एंडपॉइंट पर हर सफल कॉल का एक क्रेडिट लगता है। /api/astro/chat/, /api/astro/pdf/horoscope/ और /api/astro/pdf/yearbook/ पर 25-25 लगते हैं — इन्हें लूप और दोबारा कोशिश वाले कोड से दूर रखें।
विफल कॉल मुफ़्त हैं: गणना से पहले क्रेडिट अलग रख लिए जाते हैं और 2xx के अलावा किसी भी उत्तर पर लौटा दिए जाते हैं, और उस उत्तर में X-Credits-Charged: 0 होता है।
शुल्क वाले उत्तरों में X-Credits-Cost, X-Credits-Charged और X-Credits-Remaining होते हैं, और प्रति मिनट की सीमा वाले X-RateLimit-Limit और X-RateLimit-Remaining भी। बैलेंस का हिसाब ख़ुद रखने के बजाय इन्हें पढ़ें।
क्रेडिट ख़त्म होने पर 402 मिलता है, message में insufficient_credits के साथ; उसके data में cost_credits, credits_remaining और recharge_url होते हैं। जब तक प्लान अपग्रेड न हो या उसका कोटा रीसेट न हो, दोबारा कोशिश करने से कुछ नहीं होगा।
प्रति मिनट की सीमा पार होने पर 429 मिलता है, message में api_key_rate_limited और साथ में Retry-After हेडर (data में retry_after_seconds भी)। दोबारा भेजने से पहले उतनी देर रुकें।
गलत रूप वाली, रद्द या अवधि ख़त्म हो चुकी कुंजी पर 401 invalid_api_key मिलता है। जिस रूट, स्कोप या IP पते की अनुमति आपकी कुंजी को नहीं है, उस पर 403 endpoint_not_allowed, scope_not_allowed या ip_not_allowed मिलता है।
कुंजी और क्रेडिट की जाँच से आई त्रुटियाँ { "error": "…", "message": "insufficient_credits", "is_error": true, "data": { … } } जैसी दिखती हैं: message का कोड देखकर फ़ैसला करें। गणना वाले उत्तर विफल होने पर { "data": {}, "status": 400, "is_error": true, "message": "…" } ढाँचा इस्तेमाल करते हैं, जिसमें कारण message में लिखा होता है। दोनों में is_error होता है।
दोनों PDF एंडपॉइंट JSON नहीं, सीधे PDF (application/pdf) लौटाते हैं। बॉडी को फ़ाइल में लिख लें; बाद में डाउनलोड करने के लिए कोई लिंक नहीं होता।

ज्योतिष

वैदिक एंडपॉइंट निरयन हैं और अयनांश का संशोधन सर्वर पर ही कर देते हैं; /api/astro/western/ रूट डिफ़ॉल्ट रूप से सायन हैं। नतीजे में से अयनांश ख़ुद न घटाएँ।
/api/astro/kp-chart/ निरयन राशिचक्र पर प्लेसिडस भाव-संधियाँ लेता है, इसलिए एक ही जन्म के लिए उसके भाव /api/astro/chart/ से अलग हो सकते हैं। यह KP पद्धति है, कोई असंगति नहीं।
राशिफल राशि पर आधारित भविष्यवाणी है, इसमें जन्म कुंडली नहीं लगती: जन्म का ब्योरा नहीं, बल्कि rashi में राशि का अंग्रेज़ी नाम भेजें, जैसे leo।
जब तक आप seed न भेजें, टैरो के पत्ते बेतरतीब निकलते हैं। हर उत्तर में वह seed होता है जिससे पत्ते निकले, इसलिए अगर किसी रीडिंग को बाद में हूबहू दिखाना हो तो उसे सँभाल लें।
/api/astro/numerology/iching/ एक तारीख़ और नाम को अंकों के हिसाब से 64 हेक्साग्राम में से किसी पर रखता है। कुछ फेंका नहीं जाता, इसलिए न बदलती रेखाएँ होती हैं, न दूसरा हेक्साग्राम।

आगे

फ़ील्ड के फ़ॉर्मैटअनुरोध के सटीक फ़ॉर्मैट क्या है, क्या नहींAPI में क्या है और कहाँ ख़त्म होता है