ऑथेंटिकेशन
एक हेडर, एक कुंजी, और गिनी-चुनी त्रुटियाँ, जिनमें हर एक का साफ़ मतलब है।
हेडर
हर अनुरोध में अपनी कुंजी X-API-Key के रूप में भेजें। न कोई OAuth, न टोकन का लेन-देन, न कुछ रीफ़्रेश करना।
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 }'कुंजी का फ़ॉर्मैट
कुंजी कुछ ऐसी दिखती है: yt_live_a1b2c3d4_x9K2mQ7vB4nR8sL1wY6tZ3pC5hJ0dF — ब्रांड, एनवायरनमेंट, आठ अक्षरों का सार्वजनिक प्रीफ़िक्स, और फिर गुप्त हिस्सा।
yt_live_…आपके बैलेंस से असली क्रेडिट ख़र्च करती है।yt_test_…डेवलपमेंट के लिए है, और आपके उपयोग के रिकॉर्ड में अलग से चिह्नित होती है।
प्रीफ़िक्स जान-बूझकर सार्वजनिक और खोजने लायक रखा गया है। अगर कभी कोई कुंजी किसी सार्वजनिक रिपॉज़िटरी में लीक हो जाए, तो सिर्फ़ प्रीफ़िक्स से उसे ढूँढकर रद्द किया जा सकता है, गुप्त हिस्से की ज़रूरत नहीं पड़ती।
एक बार दिखती है, हैश के रूप में रखी जाती है
कुंजी सिर्फ़ एक बार, बनाते समय दिखाई जाती है। हम केवल उसका SHA-256 हैश रखते हैं, इसलिए न कोई एडमिन और न डेटाबेस की कॉपी उसे वापस ला सकती है — यानी हम सचमुच उसे दोबारा नहीं भेज सकते। बाद में आपको सिर्फ़ प्रीफ़िक्स और आख़िरी चार अक्षर दिखते हैं, जो सूची में दो कुंजियों को अलग पहचानने के लिए काफ़ी हैं।
कुंजी खो गई? नई बनाइए और पुरानी रद्द कर दीजिए। यह हमसे पूछने से जल्दी है, और हम भी यही कर पाते।
त्रुटियाँ, और कौन-सी ऑथेंटिकेशन की समस्या नहीं हैं
हर त्रुटि उसी मानक ढाँचे में आती है, जिसमें is_error: true होता है और message में एक स्थिर मशीन कोड। कोड देखकर फ़ैसला करें, लिखे हुए वाक्य देखकर नहीं।
| स्टेटस | message | मतलब | क्या करें |
|---|---|---|---|
| 401 | invalid_api_key | कुंजी है ही नहीं, गलत रूप में है, रद्द हो चुकी है या उसकी अवधि ख़त्म हो गई है। | जाँचें कि X-API-Key हेडर सच में हम तक पहुँचा। अगर कुंजी बदली है, तो नई कुंजी डिप्लॉय करें। |
| 402 | insufficient_credits | कुंजी सही है। बैलेंस ख़ाली है। | अपना प्लान अपग्रेड करें या मासिक रीसेट का इंतज़ार करें। यह ऑथेंटिकेशन की समस्या नहीं है — नई कुंजी बनाने से कुछ नहीं होगा। |
| 403 | endpoint_not_allowed | यह रूट API कुंजी से नहीं चलता: पाथ या मेथड गलत है, या एंडपॉइंट हटा दिया गया है। | रूट और मेथड को संदर्भ से मिलाएँ। न दोबारा कोशिश से कुछ होगा, न नई कुंजी से। |
| 403 | scope_not_allowed | कुंजी के पास वह स्कोप नहीं है जो इस एंडपॉइंट को चाहिए। | सही स्कोप वाली कुंजी बनाएँ, या सभी स्कोप के लिए स्कोप ख़ाली छोड़ दें। |
| 403 | ip_not_allowed | कुंजी पर IP अनुमति सूची लगी है और अनुरोध ऐसे पते से आया जो सूची में नहीं है। | अनुमति वाले IP से कॉल करें, या सही IP वाली कुंजी बनाएँ — या कोई IP न डालें, ताकि हर जगह से चले। |
| 403 | account_suspended | खाता निलंबित है, इसलिए उसकी हर कुंजी ठुकरा दी जाती है। | सहायता टीम से संपर्क करें। नई कुंजी बनाने से कुछ नहीं होगा। |
| 429 | api_key_rate_limited | इस कुंजी से एक मिनट में बहुत ज़्यादा अनुरोध। | रुकें, और Retry-After हेडर में दिए सेकंड बीतने के बाद दोबारा भेजें। |
| 400 | (फ़ील्ड की त्रुटियाँ) | अनुरोध की बॉडी में गड़बड़ी है। message में हर गलत फ़ील्ड का नाम है। | message पढ़ें — उसमें साफ़ लिखा होता है। इस पर कभी शुल्क नहीं लगता। |
एक बात दोहराने लायक है: 402 ऑथेंटिकेशन की विफलता नहीं है। कुंजी ठीक है, बस बैलेंस ख़ाली है। लोग अक्सर नई कुंजी बना लेते हैं, जो गलत क़दम है और उससे कुछ नहीं बदलता।
क्रेडिट वाले हेडर
हर उत्तर में लिखा होता है कि कॉल पर कितना लगा और कितना बचा, ताकि ख़र्च देखने के लिए दूसरा अनुरोध न भेजना पड़े।
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 callलॉग करने लायक हेडर X-Credits-Charged है। विफल अनुरोध पर यह हमेशा 0 बताता है: गणना शुरू होने से पहले क्रेडिट अलग रख लिया जाता है, और ठीक से जवाब न मिले तो लौटा दिया जाता है। इसलिए डिबग करते समय गलत इंटीग्रेशन बैलेंस ख़ाली नहीं कर सकता।
दर सीमा
सीमा हर कुंजी पर, प्रति मिनट लगती है। इसका मक़सद आपको राशन देना नहीं, लीक हुई कुंजी के नुक़सान को रोकना है। सीमा पार होने पर 429 मिलता है, साथ में Retry-After हेडर, जिसमें सेकंड लिखे होते हैं — तुरंत दोबारा भेजने के बजाय उतनी देर रुकें। उत्तर में X-RateLimit-Limit और X-RateLimit-Remaining भी होते हैं।
429 पर कभी शुल्क नहीं लगता। अगर आम कामकाज में ही सीमा पार हो रही है, तो हमसे सीमा बढ़ाने को कहें।
कुंजी को सुरक्षित रखना
- कॉल अपने सर्वर से करें, ब्राउज़र से नहीं। फ़्रंट-एंड बंडल या मोबाइल ऐप में रखी कुंजी, नाम कुछ भी हो, सार्वजनिक कुंजी ही है। कोई भी उसे पढ़कर आपका बैलेंस ख़र्च कर सकता है।
- इसे एनवायरनमेंट वेरिएबल या सीक्रेट मैनेजर में रखें। इसे कभी कमिट न करें।
- हर एनवायरनमेंट के लिए अलग कुंजी रखें, ताकि एक को रद्द करने पर बाकी बंद न हों।
- कुंजी बदलने का क्रम: नई कुंजी बनाएँ, उसे डिप्लॉय करें, फिर पुरानी रद्द करें — इसी क्रम में, ताकि बीच में कुछ भी बंद न हो।
- कुंजी लीक होने का ज़रा भी शक हो तो तुरंत रद्द करें। रद्द करने का असर उसी पल होता है, और बचे हुए क्रेडिट पर कोई असर नहीं पड़ता।
यह सब आप अपने कुंजियों वाले पेज पर सँभाल सकते हैं।