API त्रुटियाँ और उनका मतलब
Didit API का हर HTTP status व्यावहारिक रूप से क्या दर्शाता है - keys और permissions पर 401 और 403, 402 जैसी बैलेंस समस्याएँ, 429 rate limits, और error body कैसे पढ़ें।
पहले रिस्पॉन्स बॉडी पढ़ें। Didit की त्रुटियों में एक मैसेज होता है और अक्सर एक detail code भी होता है जो असली समस्या बताता है - अकेले status से शायद ही कुछ पता चलता है। 401 का मतलब है key की समस्या, 403 का मतलब है permissions या environment, 429 का मतलब है rate limiting, और बैलेंस की त्रुटि कोड की नहीं बल्कि credits की समस्या है।
#पहले बॉडी पढ़ें
HTTP status आपको श्रेणी बताता है। बॉडी बताती है कि असल में क्या हुआ। किसी API integration को डीबग करने में बर्बाद होने वाला लगभग हर घंटा status code का अंदाज़ा लगाने में जाता है, जबकि जवाब उस response में होता है जिसे नज़रअंदाज़ कर दिया गया।
- डिसेबल की गई या गलत application की key आमतौर पर 401 का कारण होती है।
- Last used से पता चलता है कि जो key आप भेज रहे हैं वह समझ रहे हैं, वही असल में पहुँच रही है या नहीं।
- अगर कोई key लीक हो सकती है तो secret rotate करें - 401 मिलना, breach से बेहतर है।
हर असफल कॉल पर, हर environment में, पूरी error body - status, headers, और payload - लॉग करें। आपको इसकी ज़रूरत पड़ेगी, और बाद में इसे दोबारा जुटाना कहीं ज़्यादा मुश्किल होता है।
#हर status का सामान्य मतलब
| Status | सामान्य कारण |
|---|---|
| 400 | गलत तरीके से बना request - कोई ज़रूरी field गायब, गलत enum value, या गलत आकार का nested object |
| 401 | Authentication विफल। x-api-key header गायब है, गलत फॉर्मेट में है, या मान्य key नहीं है |
| 403 | Authenticated है लेकिन अनुमति नहीं है। गलत environment, आपकी key के पास न होने वाली permission, या आपके account पर सक्षम न किया गया feature |
| 404 | संसाधन मौजूद नहीं है - या जिस key का इस्तेमाल हुआ उससे अलग किसी application के तहत मौजूद है |
| 409 | मौजूदा स्थिति के साथ टकराव, जैसे कोई action जो पहले ही लिया जा चुका है |
| 422 | Request सही फॉर्मेट में था लेकिन values स्वीकार्य नहीं हैं - यह syntax नहीं बल्कि validation की विफलता है |
| 429 | Rate limited। नीचे देखें |
| 5xx | Didit की तरफ से कोई समस्या। backoff के साथ फिर से कोशिश करें, और status.didit.me देखें |
#401 बनाम 403 - यह फर्क समय बचाता है
401 का मतलब है कि key स्वीकार ही नहीं हुई। जांचें कि आप x-api-key भेज रहे हैं, value में कोई अतिरिक्त space या quotes तो नहीं हैं, और आपने गलती से webhook signing secret को API key की जगह पेस्ट तो नहीं कर दिया - ये दोनों अलग चीज़ें हैं और यह गलती आम है।
403 का मतलब है कि key मान्य है लेकिन यह कॉल अनुमति प्राप्त नहीं है। तीन कारण, क्रम में:
- Environment मेल न खाना। Sandbox-only fields (जैसे
sandbox_scenario) live application पर अस्वीकार कर दी जाती हैं, और इसका उल्टा भी सच है। Live और sandbox अलग-अलग applications हैं जिनकी अलग-अलग keys होती हैं। - Permission की कमी। कुछ operations के लिए ऐसी permissions चाहिए जो आपकी key या role के पास नहीं हैं। अगर आपको session create-and-manage का अधिकार चाहिए जो आपके पास नहीं है, तो यह कोड में बदलाव का नहीं बल्कि support से मांगने का मामला है।
- Feature सक्षम नहीं है। कुछ क्षमताएँ हर organization के हिसाब से अलग से दी जाती हैं। जिस feature के बारे में आपको लगता है कि वह आपके पास होना चाहिए, उस पर 403 मिलना - कॉल दोबारा लिखने से पहले पूछने लायक बात है।
सिर्फ देखकर sandbox key और live key में फर्क करने का कोई तरीका नहीं है, इसलिए इन्हें अपने secret manager में साफ़-साफ़ अलग नामों के तहत रखें और कभी भी एक ही environment variable को "जो भी key अभी चालू है" के लिए इस्तेमाल न होने दें। टेस्ट environment में live key इस्तेमाल होने से असली credits खर्च होते हैं।
#404 जो मिलना नहीं चाहिए था
अगर कोई session या workflow 404 देता है और आपको यकीन है कि वह मौजूद है, तो आमतौर पर जवाब यह होता है कि वह किसी अलग application के तहत मौजूद है, न कि उस application के तहत जिसकी key से आपने authenticate किया। Resources अपने application तक सीमित होते हैं; application A की key, application B के sessions नहीं देख सकती।
#Balance और credit से जुड़ी त्रुटियाँ
अगर कोई कॉल इसलिए विफल होती है क्योंकि पर्याप्त credits नहीं हैं, तो यह कोड की समस्या नहीं है। Workflow में कोई paid feature शामिल है और आपका balance उसे कवर नहीं कर पा रहा। यह "API टूट गया" जैसी रिपोर्ट्स में सबसे आम है, और इसका कारण लगभग हमेशा white label, AML, या NFC होता है जो किसी ऐसे workflow में है जिसे मुफ़्त माना जा रहा था। देखें "not enough credits" त्रुटि को ठीक करना।
#429 rate limiting
Limits प्रति identifier लागू होती हैं - आपकी x-api-key, या अगर कोई key नहीं भेजी गई तो आपका client IP - हर scope का अपना अलग counter होता है, 60-सेकंड की sliding window पर।
Global defaults:
| Scope | Methods | Limit |
|---|---|---|
| सामान्य reads | GET | 600 / मिनट |
| सामान्य writes | POST, PATCH, DELETE | 300 / मिनट |
कुछ ज़्यादा असर वाले endpoints की global limit के अतिरिक्त अपनी सख्त limits होती हैं, और जो भी scope पहले अपनी सीमा पार करता है वही 429 लौटाता है। पूरी table: rate limiting।
429 को exponential backoff और jitter के साथ हैंडल करें। किसी rate limit के खिलाफ लगातार retry करने से समस्या और बढ़ जाती है और आप अनिश्चित काल तक limited रह सकते हैं।
429 का सबसे आम कारण batch jobs होते हैं - जैसे कोई रात की import प्रक्रिया जो कुछ ही सेकंड में सैकड़ों create कॉल्स भेज दे। concurrency बढ़ाते रहने के बजाय काम को फैला दें जब तक त्रुटि आना बंद न हो जाए।
#Feature-level detail codes
HTTP statuses के अलावा, अलग-अलग checks provider-level समस्याओं के लिए अपने खुद के detail codes लौटाते हैं - उदाहरण के लिए कोई registry integration जिसकी किसी खास देश में किसी खास product तक पहुंच नहीं है। जब आपको कोई ऐसा code मिले, तो वह स्थिति को सटीक रूप से बताता है, इसलिए पूछते समय उसे कोट करें।
अगर किसी response में वह detail code नहीं है जिसकी आप catalogue के हिसाब से उम्मीद करते हैं, तो उसे किसी तरह से टालने के बजाय रिपोर्ट करना बेहतर है - एक गायब code असल में एक कमी है, और यह अगले व्यक्ति के लिए भी उसी समस्या को और मुश्किल बना देता है।
#खाली रिस्पॉन्स सफलता नहीं होते
कोई provider-backed check जो खाली body लौटाए, वह साफ़ result के बराबर नहीं है। "कोई data नहीं" को अपने कोड में एक अलग स्थिति के रूप में मानें, न कि उसे pass मान लें - खासकर database validation और wallet screening के लिए, जहां किसी unprovisioned service और असली no-match में बाहर से देखने पर फर्क करना मुश्किल हो सकता है।
#Error paths टेस्ट करना
Sandbox डिटरमिनिस्टिक तरीके से खास failures को force करता है, जो आपकी error हैंडलिंग टेस्ट करने का एकमात्र समझदारी भरा तरीका है। देखें sandbox में टेस्ट करना।