1. प्रश्न
एक B2B डेटा API हज़ारों डेवलपर टीमों को सेवा प्रदान करता है। एक रिलीज़ के बाद, सपोर्ट टिकटों में लगातार यह कहा जा रहा है कि अनुरोध विफल हो रहे हैं और उन्हें ठीक करने का तरीका नहीं बताया जा रहा है। इंजीनियरिंग टीम अधिक आंतरिक लॉग दिखाना चाहती है, जबकि सेल्स टीम प्रत्येक ग्राहक के लिए कस्टम एरर टेक्स्ट की मांग करती है। प्रोडक्ट मैनेजर के रूप में, मौजूदा क्लाइंट्स को तोड़े बिना एक एक्शन लेने योग्य API एरर अनुभव डिज़ाइन करें।
2. सीमाएं और स्पष्टीकरण
- क्लाइंट-इनपुट, प्रमाणीकरण (authentication) और प्राधिकरण (authorization), रेट-लिमिट, डिपेंडेंसी, और आंतरिक-सेवा विफलताओं को अलग करें; प्रत्येक विफलता को केवल एक 500 एरर में न समेटें।
- रिस्पॉन्स को मशीन हैंडलिंग, डेवलपर डायग्नोसिस, और एंड-यूज़र प्रेजेंटेशन की ज़रूरतों को आपस में मिलाए बिना पूरा करने योग्य बनाएं।
- मौजूदा SDKs और लॉग फ़ॉर्मेट तुरंत नहीं बदले जा सकते, इसलिए योजना में पुराने क्लाइंट्स और क्रमिक माइग्रेशन का समर्थन होना चाहिए।
- कॉलर को सीधे कभी भी संवेदनशील स्टैक्स (stacks), टोकन, यूज़र डेटा या आंतरिक टोपोलॉजी न लौटाएं।
3. प्रोडक्ट डायग्नोसिस फ्रेमवर्क
समस्या को तीन प्रश्नों में विभाजित करें: क्या हुआ, इसे कौन ठीक कर सकता है, और आगे क्या होना चाहिए। एक एरर रिस्पॉन्स को एक स्थिर मशीन-पठनीय कोड, एक सुरक्षित मानव सारांश, वैकल्पिक संरचित विवरण, और एक सपोर्ट कोरिलेशन ID की आवश्यकता होती है; डॉक्स और SDKs कोड को एक समाधान से मैप करते हैं। प्रोडक्ट विश्लेषण को केवल कुल विफलता दर ही नहीं, बल्कि एरर के बाद रिकवरी दर, बार-बार दोहराए जाने वाले पुनः प्रयास (retries), विफलता से सफलता तक का समय, एरर श्रेणी के अनुसार सपोर्ट टिकट, और वर्शन वितरण को भी ट्रैक करना चाहिए।
4. संदर्भ समाधान
errorResponse:
status: canonicalStatusCode
code: stableProductErrorCode
message: safeHumanSummary
details:
reason: machineActionableReason
fieldViolations: optionalFieldErrors
retryAfter: optionalDelay
requestId: supportCorrelationId
docsUrl: versionedFixGuide
clientFlow(error):
classify(error.status, error.code)
if retryable: backoffAndRetry(error.details.retryAfter)
else if fieldError: highlightFields(error.details.fieldViolations)
else: showDocsAndRequestId(error.docsUrl, error.requestId)स्थिर कैनोनिकल स्टेटस कोड्स का एक छोटा सेट परिभाषित करें, फिर कार्रवाई योग्य कारणों के लिए प्रोडक्ट एरर कोड्स का उपयोग करें। फ़ील्ड उल्लंघन, पुनः प्रयास का समय और दस्तावेज़ीकरण लिंक संरचित विवरण में रखें। कंसोल कोड के आधार पर सुधार के चरण दिखाता है, जबकि SDKs एरर को कैच करने योग्य प्रकारों में मैप करते हैं और मूल कोड को सुरक्षित रखते हैं। सर्विस आंतरिक रूप से पूर्ण डायग्नोस्टिक्स रिकॉर्ड करती है लेकिन केवल एक सुरक्षित सारांश और कोरिलेशन ID ही लौटाती है।
5. ट्रेड-ऑफ और रोलआउट रणनीति
बारीक एरर कोड मार्गदर्शन को अधिक सटीक बनाते हैं लेकिन अनुकूलता और दस्तावेज़ीकरण लागत बढ़ाते हैं। उच्च-मात्रा वाले एरर से शुरुआत करें जिन्हें डेवलपर्स ठीक कर सकते हैं, फिर छोटी श्रेणियों के लिए विवरण जोड़ें; प्रति टेनेंट (tenant) कोई कस्टम प्रोटोकॉल न बनाएं। नए फ़ील्ड बैकवर्ड कम्पैटिबल होने चाहिए। एक बार जब किसी कोड का अर्थ सार्वजनिक हो जाए, तो उसे स्थिर रखें: पुराने क्लाइंट्स पुराना फ़ॉर्मेट प्राप्त करना जारी रखते हैं जबकि नए SDKs संरचित विवरण का विकल्प चुनते हैं। आंशिक-विफलता (partial-failure) रिस्पॉन्स में सावधानी बरतनी चाहिए क्योंकि वे क्लाइंट ब्रांचिंग बढ़ाते हैं; उन्हें केवल तभी पेश करें जब किसी बैच API की स्पष्ट आवश्यकता हो।
6. सत्यापन और अवलोकनीयता (Observability)
- सपोर्ट टिकटों और कॉल लॉग्स का नमूना लें, प्रत्येक विफलता को डायग्नोस करने योग्य, ठीक करने योग्य, और अनावश्यक रूप से पुनः प्रयास किया गया या नहीं के रूप में लेबल करें।
- प्रमाणीकरण, फ़ील्ड सत्यापन, रेट लिमिट्स, डिपेंडेंसी टाइमआउट्स और अज्ञात विफलताओं के लिए कॉन्ट्रैक्ट टेस्ट लिखें, जिसमें स्टेटस, कोड और डॉक्स URL की जांच की जाए।
- धीरे-धीरे नए फ़ॉर्मेट को रोल आउट करें और रिकवरी दर, बार-बार के पुनः प्रयास, टिकट की मात्रा और SDK अपवाद-कैप्चर (exception-capture) दर की तुलना करें।
- एरर रिस्पॉन्स में अज्ञात कोड्स, पुराने क्लाइंट्स की हिस्सेदारी, दस्तावेज़-क्लिक से सफलता में रूपांतरण, और संवेदनशील फ़ील्ड के रिसाव की निगरानी करें।
7. सामान्य गलतियाँ
- कॉलर्स को एक स्थिर कोड और सुधार कार्रवाई दिए बिना अधिक लॉग या स्टैक्स दिखाना।
- HTTP स्टेटस में सभी व्यावसायिक अर्थों को एनकोड करना जिससे क्लाइंट्स को स्ट्रिंग्स पार्स करने के लिए मजबूर होना पड़े।
- एक कथित तौर पर अनुकूल संदेश में आंतरिक अपवाद, टोकन, या पूर्ण अनुरोध पैरामीटर डालना।
- एक ही रिलीज़ में कोड्स का नाम बदलना या हटाना और अपग्रेड के दौरान पुराने SDKs को तोड़ देना।
8. इंटरव्यू स्कोरिंग बिंदु
सुधार की ज़िम्मेदारी के अनुसार एरर का वर्गीकरण करता है
उम्मीदवार को इनपुट, अनुमति, रेट-लिमिट, डिपेंडेंसी और आंतरिक विफलताओं को अलग करना चाहिए और प्रत्येक के लिए कॉलर की कार्रवाई और सर्विस की ज़िम्मेदारी बतानी चाहिए।
एक स्थिर और सुरक्षित एरर मॉडल डिज़ाइन करता है
उत्तर में आंतरिक विवरणों को उजागर किए बिना मशीन-पठनीय कोड, सुरक्षित सारांश, संरचित विवरण, कोरिलेशन IDs और वर्शन वाले डॉक्स शामिल होने चाहिए।
अनुभव को प्रोडक्ट मेट्रिक्स से जोड़ता है
उम्मीदवार को केवल विफलता दर के बजाय रिकवरी दर, बार-बार के पुनः प्रयास, ठीक करने का समय, टिकट और वर्शन वितरण का उपयोग करना चाहिए।
एक अनुकूल माइग्रेशन की योजना बनाता है
उम्मीदवार को पुराने-फ़ॉर्मेट की अनुकूलता, क्रमिक SDK एडॉप्शन, रोलआउट और रोलबैक मानदंड, और यह समझाना चाहिए कि कब एक जटिल आंशिक-विफलता प्रोटोकॉल पेश नहीं करना है।