API Errors और उन्हें संभालने की गाइड: 402, 429, 403 क्या करें

मुख्य बातें

• हर error body में तीन चीज़ें होती हैं: code, message और requestId। branching code या HTTP status पर करें, message पर नहीं।
• 402 PAYMENT_REQUIRED: fulfilment wallet का balance इस call के लिए कम है। retry से कुछ नहीं होगा, पहले wallet भरें।
• 429 TOO_MANY_REQUESTS: reference के उदाहरण में सीमा "60 requests per 60 seconds for this endpoint" लिखी है। यह सीमा endpoint के हिसाब से लगती है। backoff के साथ retry करें।
• 403 FORBIDDEN: key सही है पर scope नहीं है (जैसे verification.pan.read)। नई key या scope बदलाव चाहिए, retry नहीं।
• 401 UNAUTHORIZED: key गायब है या गलत है। Authorization header, key का environment (sk_test_ या sk_live_) और कोई extra space देखें।
• 400 BAD_REQUEST: input का format गलत है, जैसे PAN ABCDE1234F format में नहीं। यह call तक पहुँचने से पहले ही पकड़ लिया जाता है, इसलिए बिना input बदले retry न करें।
• 502 INTERNAL_ERROR का संदेश "Unable to reach the order/customer service right now" है। यह upstream की दिक्कत है, इसलिए सीमित retry ठीक है।
• सफल verification पर ही usage दर्ज होता है। valid: false वाला नतीजा भी पूरा और billable verification है, error नहीं।
• support को लिखते समय requestId ज़रूर भेजें, यही सबसे तेज़ रास्ता है।

रात 2 बजे error आया: पहले पाँच मिनट में क्या करें?

मान लीजिए आप "कावेरी फिनसर्व" नाम की एक काल्पनिक छोटी NBFC के backend पर काम करते हैं। loan onboarding में हर आवेदक का PAN POST /v1/verify/pan से जाँचा जाता है। रात दो बजे dashboard लाल है। घबराने की ज़रूरत नहीं, पाँच मिनट का यह क्रम काफी है।

पहला मिनट: status code गिनिए। अपने log या APM में पिछले 15 मिनट के failures को HTTP status के हिसाब से group कीजिए। अगर लगभग सभी एक ही code के हैं (मान लें सब 402), तो कारण एक ही है और इलाज भी एक। अगर अलग-अलग codes का मिश्रण है, तो पहले सबसे ज़्यादा वाले से शुरू करें।

दूसरा मिनट: एक असली response body खोलिए। log से एक failed call चुनिए और उसका error.code और error.requestId निकालिए। अगर आपने body log ही नहीं की थी, तो यही आपकी पहली सीख है (इसका उपाय आगे "requestId और logging" वाले खंड में है)।

तीसरा मिनट: फ़ैसला तालिका से कीजिए।

चौथा मिनट: असर घटाइए। अगर 402 है तो नए आवेदकों को "थोड़ी देर बाद कोशिश करें" का संदेश दिखाइए और queue में रखिए। हर बार नई call मत मारिए, क्योंकि हर failed call सिर्फ़ शोर बढ़ाती है।

पाँचवाँ मिनट: मालिक को बताइए। 402 में फ़ैसला पैसे वाला है, यह किसी को जगाकर wallet भरवाने का मामला है। 403 में आपके team के किसी admin को नई key बनानी होगी। 502 में आपके हाथ में कुछ नहीं, पर आप requestId इकट्ठा करके support को भेज सकते हैं।

इस क्रम का फ़ायदा यह है कि आप अंदाज़े से नहीं, सबूत से चलते हैं। आगे के खंडों में हर code को अलग से खोला गया है।

हर error की शक्ल एक जैसी क्यों है और उसे कैसे पढ़ें?

StampMitra की reference में साफ़ लिखा है कि API की हर error एक सामान्य रूप में बदलकर लौटाई जाती है, और stack trace या database की कच्ची error कभी बाहर नहीं आती। नतीजा यह कि parsing का code एक ही जगह लिखना काफी है। यह असली उदाहरण है (402 का):

{
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Insufficient fulfilment wallet balance to cover this call.",
    "requestId": "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"
  }
}

तीनों field का काम

code एक स्थिर शब्द है, जैसे BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, PAYMENT_REQUIRED, TOO_MANY_REQUESTS, INTERNAL_ERROR। मशीन के लिए यही असली पहचान है। अपने branching में इसे या HTTP status को इस्तेमाल कीजिए।

message इंसान के पढ़ने के लिए है। reference में हर code के साथ जो वाक्य दिखते हैं (जैसे "pan must match the format ABCDE1234F") वे उदाहरण हैं। इनके शब्द भविष्य में बदल सकते हैं, इसलिए message पर if (msg.includes(...)) जैसा code न लिखें। हाँ, log में और developer के debugging के लिए इसे ज़रूर रखें।

requestId हर response की अपनी पहचान है, एक UUID। इसे उस call की "रसीद" समझिए। जब आप support से पूछते हैं कि "मेरी call क्यों फेल हुई?", तो यही id उन्हें सीधे उस घटना तक ले जाती है।

पर मत भूलिए: कुछ errors body में नहीं बदलते

सब कुछ एक ही शक्ल में आए, इसकी उम्मीद रखिए, पर defensive रहिए। अगर किसी वजह से response JSON न हो (जैसे बीच में कोई proxy या load balancer आपका request काट दे), तो आपका parser टूटना नहीं चाहिए। नीचे Node.js वाले handler में हमने try/catch इसी वजह से रखा है।

एक और बारीकी: team invite accept वाले endpoint का एक उदाहरण HTTP 200 लौटाता है, पर body में { "status": "signup_required", "email": "..." } होता है। यानी हर "काम न हुआ" का मतलब error नहीं होता। हर endpoint का response उदाहरण देखकर ही branching तय करें।

Status code cheat sheet: कौन सा code क्या कहता है?

नीचे की तालिका सिर्फ़ उन्हीं codes की है जो StampMitra की reference में असली error examples के रूप में दर्ज हैं। इनके बाहर के codes के बारे में हम कोई दावा नहीं करते।

इस तालिका से तीन बातें निकलती हैं। पहली, 4xx का मतलब आम तौर पर "आपकी तरफ़ कुछ ठीक करना है" है, इसलिए retry से पहले कारण समझें। दूसरी, 502 अकेला code है जो reference में upstream की समस्या के रूप में दिया गया है। तीसरी, 429 पूरी तरह से अस्थायी है, पर बाकी 4xx तब तक नहीं बदलेंगे जब तक आप कुछ बदलें नहीं।

एक सावधानी: 400 कभी-कभी सिर्फ़ format की गलती नहीं होता। reference में commonMeteringErrors के पहले उदाहरण का label "Validation error / not entitled" है, यानी किसी service के लिए आपका access न होना भी 400 के रूप में दिख सकता है। इसलिए 400 में message ज़रूर पढ़ें, भले ही उस पर branching न करें।

402 आया तो क्या करें? wallet balance की कहानी

StampMitra की कई सेवाएँ fulfilment wallet से चलती हैं। reference में लिखा है कि priced service पर usage तभी दर्ज होता है और wallet तभी debit होता है जब verification सफलतापूर्वक पूरी हो जाए। 402 वह स्थिति है जब wallet में इतना balance नहीं कि यह call उसे पूरा कर सके। body ऐसी होती है: "Insufficient fulfilment wallet balance to cover this call."

402 को "retry" से मत सुलझाइए

यह सबसे आम गलती है। developer सोचता है कि कोई अस्थायी गड़बड़ है और exponential backoff लगा देता है। पर balance तो तब तक नहीं बदलेगा जब तक कोई उसमें पैसा न डाले। हर retry वही 402 लाएगा और ऊपर से आपका rate limit भी खाएगा, यानी थोड़ी देर में 402 के साथ-साथ 429 भी दिखने लगेगा।

सही तरीका

1. 402 आने पर उस call को "रुकी हुई" हालत में रखिए, दोबारा मत भेजिए।
2. अपने ops या finance वाले को सूचना दीजिए। StampMitra dashboard में wallet balance का card दिखता है, वहीं से स्थिति देखी जा सकती है।
3. balance भरने के बाद रुकी हुई calls को धीरे-धीरे दोबारा चलाइए।
4. उपयोगकर्ता को साफ़ संदेश दीजिए, जैसे "सत्यापन अभी उपलब्ध नहीं है, थोड़ी देर में फिर कोशिश करें।" अपने ग्राहक को यह मत बताइए कि आपका wallet खाली है।

पहले से कैसे बचें

balance के लिए एक अलर्ट रखिए, इस्तेमाल के अनुमान के हिसाब से। हर सफल PAN call पर आपका खर्च ₹5 है (दर की ताज़ा जानकारी pricing पेज पर देखें)। इसलिए एक दिन में कितने आवेदक आते हैं, इसका अंदाज़ा लगाकर तय कीजिए कि balance कितने दिन चलेगा। त्योहारों के सीज़न या किसी campaign से पहले balance बढ़ाकर रखना सस्ता बीमा है, क्योंकि campaign के बीच 402 आने का मतलब खोए हुए आवेदक हैं।

402 और billing की सीमा

ध्यान रहे कि reference के मुताबिक failed validation (400) या upstream error (502) पर usage दर्ज नहीं होता, क्योंकि usage "सफल response के बाद" दर्ज होता है। यानी 402 की चिंता असल में सफल calls की गिनती से जुड़ी है, गलत input से wallet खाली नहीं होता। फिर भी अपनी invoice और dashboard से मिलान करके देखते रहना अच्छी आदत है।

429 आया तो क्या करें? rate limit को समझदारी से संभालना

reference में 429 का उदाहरण है: "Rate limit exceeded: 60 requests per 60 seconds for this endpoint." यहाँ दो बातें ध्यान देने की हैं। एक, यह सीमा endpoint के हिसाब से है, पूरे account की एक साझा सीमा नहीं। दो, यह उदाहरण का संदेश है, और हर endpoint या हर account की असली सीमा अलग हो सकती है। इसलिए 60 को हमेशा के लिए कोड में मत लिख दीजिए। अपनी असली सीमा के लिए reference और समर्थन से पुष्टि कीजिए।

यह कब होता है

मान लें आपके पास रात में 5,000 पुराने ग्राहकों का PAN दोबारा जाँचने का batch job है। आपने एक for loop में सबको एक साथ भेज दिया। पहले मिनट के अंदर आपने अपनी सीमा पार कर ली और बाकी सब 429 से लौट आए। यही सबसे आम कारण है: burst traffic।

सही व्यवहार: धीरे चलिए, फिर backoff कीजिए

• पहले रोकिए, फिर retry कीजिए। 429 मिलते ही उस endpoint पर नई calls कुछ देर के लिए रोक दीजिए।
• Exponential backoff + jitter। पहली बार 1 सेकंड, फिर 2, फिर 4, साथ में थोड़ा random जोड़िए ताकि आपके कई workers एक ही पल पर दोबारा न टकराएँ।
• ऊपरी सीमा रखिए। तीन से पाँच कोशिशों के बाद छोड़ दीजिए और job को "बाद में" वाली queue में डाल दीजिए।
• Retry-After पर निर्भर मत रहिए। reference में किसी Retry-After header का ज़िक्र नहीं है। अगर आपका client ऐसा कोई header देखे तो उसका सम्मान कीजिए, पर आपके code में उसके बिना भी सही चलने वाला backoff होना चाहिए।

पहले से रोकिए: client-side throttle

बेहतर यह है कि 429 आने से पहले ही आप अपनी गति तय कर लें। batch job में एक सरल token bucket रखिए जो हर endpoint के लिए प्रति मिनट तय संख्या से ऊपर न जाए। अगर आपको नियमित रूप से सीमा से ज़्यादा चाहिए, तो इसे support से सीधे पूछिए, क्योंकि यह तकनीकी नहीं, खाते की बात है।

अनजाने में सीमा खाने वाले दूसरे endpoints

dashboard वाले auth endpoints भी (signup, login, forgot-password, resend-verification) reference में 429 के साथ दिखते हैं, और उनका वर्णन "प्रति IP और प्रति email" rate-limited के रूप में है। यानी अगर आपका frontend "OTP दोबारा भेजें" बटन पर तेज़ी से click होने देता है, तो उपयोगकर्ता खुद 429 पैदा कर देगा। बटन को कुछ सेकंड के लिए disable कर दीजिए।

401 और 403 में क्या फ़र्क है? और 403 का इलाज क्या है?

ये दोनों सबसे ज़्यादा उलझाते हैं। सरल तरीका: 401 का मतलब है "आप कौन हैं, यह समझ नहीं आया"। 403 का मतलब है "आप कौन हैं, यह समझ आ गया, पर आपको यह काम करने की अनुमति नहीं"।

401: key ही नहीं पहुँची या गलत है

असली body: "Missing or invalid API key." इसके आम कारण:

• header नाम गलत है। StampMitra Authorization: Bearer <key> या x-api-key: <key> स्वीकार करता है।
• environment variable खाली है, तो header Bearer ही रह जाता है।
• key के आगे-पीछे newline या space चिपक गया (.env से पढ़ते समय आम है)।
• आपने key को कुछ और समझकर कहीं बदल डाला। कच्ची key सिर्फ़ एक बार दिखती है, इसलिए खो जाए तो नई बनानी पड़ती है।

403: key पहचानी गई, पर scope नहीं है

असली body: "API key is valid but lacks the required scope for this endpoint." हर endpoint का अपना scope है। उदाहरण: PAN verify के लिए verification.pan.read, GSTIN के लिए verification.gstin.read, order बनाने के लिए orders.create, payment intent के लिए payments.write, e-stamp की duty गणना के लिए estamp.duty.calculate। अगर आपने PAN के लिए बनी key से GSTIN call कर दिया, तो 403 मिलेगा।

403 के तीन चेहरे

sandbox की key से production endpoint?

keys environment के हिसाब से बँधी हैं: sk_test_... sandbox की और sk_live_... production की। docs के अनुसार production keys केवल KYC-approved organization के लिए हैं। अगर production में कोई service आपके लिए अभी खुली नहीं है, तो उसका असर 400 या 403 के रूप में दिख सकता है। reference में इसका सटीक status हर service के लिए अलग से नहीं लिखा है, इसलिए ऐसे में requestId के साथ support से पूछना सबसे सीधा रास्ता है। sandbox और production के अंतर पर हमारा अलग लेख है: sandbox बनाम production API keys।

403 को retry मत कीजिए

scope अपने आप नहीं बदलेगा। retry लगाने से आप सिर्फ़ rate limit खा रहे हैं। 401 और 403 को अपने code में "retry न करने वाले" वर्ग में डालिए और तुरंत alert भेजिए, क्योंकि यह configuration की गलती है, कोई अस्थायी गड़बड़ नहीं।

400, 404 और 409: आपकी तरफ़ की गलतियाँ कैसे पहचानें?

ये तीनों बताते हैं कि अनुरोध में कुछ ऐसा है जो बदलना पड़ेगा।

400 BAD_REQUEST: input जाँच में ही रुक गया

verification endpoints पर input का format शुरू में ही जाँचा जाता है, और गलत pan/gstin जैसे मान बिना verification के सीधे 400 से लौटा दिए जाते हैं। असली संदेश उदाहरण:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "pan must match the format ABCDE1234F",
    "requestId": "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"
  }
}

हर product का अपना संदेश है, जैसे "gstin must match the format 07AAAAA1111A1Z1", "vehicleNumber must match the format MH12AB1234" या bank account के लिए "accountNumber must be a 9-18 digit numeric bank account number"। इसलिए बेहतर यही है कि आप अपने frontend या API layer में यही जाँच पहले कर लें, ताकि उपयोगकर्ता को तुरंत और साफ़ भाषा में बता सकें। regex नीचे के संदेशों से मेल खाना चाहिए, पर आख़िरी अधिकार server का ही है।

400 के और रूप

• कमज़ोर password: signup और reset-password दोनों पर 10 से 72 अक्षर और upper, lower, digit, symbol चाहिए।
• गलत या expired OTP या token: "This code is invalid or has expired." और "This verification link is invalid or has expired."
• team में आख़िरी owner को हटाने या उसकी भूमिका बदलने की कोशिश: "Cannot change the role of the organization's last owner."

404 NOT_FOUND

body: "The requested resource was not found." यह तब दिखता है जब आप ऐसा id भेजते हैं जो मौजूद नहीं, जैसे गलत invite id या member का userId। एक सुझाव: e-stamp में /v1/orders/:id का id आपका externalOrderId नहीं, बल्कि B2B की तरफ़ से दिया गया order id है (reference में "B2B-assigned id" लिखा है)। इन दोनों को मत मिलाइए।

409 CONFLICT

body: "A record with these details already exists." reference में यह signup पर "Email already registered" के रूप में दिखता है। इसे error की तरह नहीं, "यह तो पहले से है" की सूचना की तरह संभालिए। उपयोगकर्ता को login का रास्ता दिखाइए, दोबारा signup का नहीं।

आम नियम

400, 404, 409 में retry बेकार है। इनमें हर बार वही जवाब आएगा। इन्हें उपयोगकर्ता तक ले जाइए (या अपने डेटा की सफ़ाई कीजिए), और log में requestId के साथ रखिए।

502 आया तो क्या करें? upstream की गड़बड़ी

verification की सभी /v1/verify/* routes एक upstream verification service पर टिकी हैं। जब वह service पहुँच से बाहर हो या कोई अप्रत्याशित त्रुटि लौटाए, तब StampMitra यह लौटाता है:

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Unable to reach the order/customer service right now",
    "requestId": "5c1c1e9e-2f7b-4b7a-9b0e-0f1a2b3c4d5e"
  }
}

ध्यान दीजिए, यह HTTP 502 है पर code है INTERNAL_ERROR। यानी branching करते समय code के नाम से यह मत मान लीजिए कि यह कोई 500 है, status भी देखिए।

क्यों अलग तरह से संभालें

यह आपकी गलती नहीं है और आपके input से भी नहीं जुड़ी। इसलिए:

• सीमित retry करें: दो से तीन बार, कुछ सेकंड के अंतर पर।
• fail-open या fail-closed का फ़ैसला पहले से तय रखिए। उदाहरण के लिए KYC में, जहाँ सत्यापन अनिवार्य है, आवेदन को "सत्यापन लंबित" दिखाना सुरक्षित है। किसी बिना सत्यापन के आवेदक को आगे बढ़ा देना नहीं।
• लगातार आए तो support को requestId के साथ बताइए। हमारी API SLA नीति में बाहरी निर्भरताओं और incident संचार की रूपरेखा दी है, और वह बिना शर्त uptime का वादा नहीं करती। इसलिए आपका design इस मानकर बनना चाहिए कि कभी-कभी upstream नहीं मिलेगा।

502 पर पैसा कटता है?

reference के अनुसार usage सिर्फ़ सफल response के बाद दर्ज होता है, इसलिए 502 पर wallet से debit की उम्मीद नहीं है। फिर भी यदि आपको कोई ऐसा मामला दिखे जहाँ 502 के बाद भी balance घटा, तो उसे requestId के साथ support को भेजिए, क्योंकि यह जाँच का विषय है।

Retry करें या न करें: फ़ैसला कैसे लें?

सबसे ज़्यादा नुकसान बिना सोचे retry करने से होता है। नीचे की तालिका को अपने code में सीधा नियम बना लीजिए।

timeout सबसे कठिन है

अगर आपको कोई response ही नहीं मिला, तो आपको पता नहीं कि call पहुँची थी या नहीं। verification में यह मामूली है, क्योंकि दोबारा भेजने पर दोबारा सत्यापन होगा। ज़्यादा से ज़्यादा आपको एक और billable call लगेगी। पर order और payment में यह गंभीर है: एक ही order दो बार बन सकता है, एक ही भुगतान दो बार माँगा जा सकता है।

इसी वजह से POST /v1/orders और POST /v1/payments/intents पर वैकल्पिक Idempotency-Key header मौजूद है। इसकी बात नीचे अलग खंड में है।

retry की कुल सीमा भी तय रखिए

सिर्फ़ हर call की कोशिशें गिनना काफी नहीं है। मान लीजिए आपके पचास workers हैं और हर एक चार बार retry करता है। उस एक मिनट में आपकी असली traffic चार गुना हो सकती है, और यही 429 को और बढ़ा देगी। इसलिए एक साझा "circuit breaker" रखिए: अगर पिछले एक मिनट में किसी endpoint पर बहुत बड़ा हिस्सा 429 या 502 रहा, तो कुछ देर के लिए नई calls रोक दीजिए और queue में जमा कीजिए। जब स्थिति सुधरे तब धीरे-धीरे खोलिए। इससे आप खुद की वजह से बने तूफ़ान से भी बचते हैं और upstream को भी साँस लेने देते हैं।

"कब retry, कब नहीं" का एक सरल नियम

अपने आप से पूछिए: क्या अगली बार कुछ बदला होगा? 429 में समय बदलेगा, 502 में upstream की हालत बदल सकती है। बाकी में कुछ नहीं बदलेगा जब तक आप खुद कुछ न बदलें। जहाँ कुछ नहीं बदलता, वहाँ retry सिर्फ़ शोर और खर्च है।

Node.js और Python में एक ही error handler कैसे लिखें?

मकसद एक ऐसा छोटा wrapper है जो हर response को तीन में बाँटे: सफल, retry लायक, और पक्की गलती। नीचे के सभी उदाहरण असली endpoint POST https://api-b2b.stampmitra.in/v1/verify/pan और reference के असली request body ({"pan":"ABCDE1234F","name":"Rahul Kumar"}) पर बने हैं।

cURL: पहले हाथ से देखिए

curl -i -X POST "https://api-b2b.stampmitra.in/v1/verify/pan" \
  -H "Authorization: Bearer $STAMPMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pan":"ABCDE1234F","name":"Rahul Kumar"}'

-i लगाने से response के headers भी दिखते हैं, जो error के समय काम आते हैं।

Node.js (Node 18+, built-in fetch)

const BASE = "https://api-b2b.stampmitra.in";
const RETRYABLE = new Set([429, 502]);

class StampMitraError extends Error {
  constructor(status, code, message, requestId) {
    super(message);
    this.status = status;
    this.code = code;
    this.requestId = requestId;
  }
}

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export async function verifyPan(pan, name, maxTries = 4) {
  for (let attempt = 1; attempt <= maxTries; attempt++) {
    let res;
    try {
      res = await fetch(`${BASE}/v1/verify/pan`, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.STAMPMITRA_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ pan, name }),
      });
    } catch (netErr) {
      // network टूटा: verification में दोबारा भेजना सुरक्षित है
      if (attempt === maxTries) throw netErr;
      await sleep(2 ** attempt * 500);
      continue;
    }

    if (res.ok) return res.json();

    let err = {};
    try {
      err = (await res.json()).error ?? {};
    } catch {
      /* body JSON नहीं था, status से काम चलाएँगे */
    }

    const e = new StampMitraError(res.status, err.code, err.message, err.requestId);
    console.error("stampmitra_error", {
      status: e.status, code: e.code, requestId: e.requestId, attempt,
    });

    if (!RETRYABLE.has(res.status) || attempt === maxTries) throw e;
    const jitter = Math.random() * 300;
    await sleep(2 ** attempt * 500 + jitter);
  }
}

Python (requests)

import os, time, random, logging
import requests

BASE = "https://api-b2b.stampmitra.in"
RETRYABLE = {429, 502}
log = logging.getLogger("stampmitra")

class StampMitraError(Exception):
    def __init__(self, status, code, message, request_id):
        super().__init__(message)
        self.status, self.code, self.request_id = status, code, request_id

def verify_pan(pan, name=None, max_tries=4):
    payload = {"pan": pan}
    if name:
        payload["name"] = name
    for attempt in range(1, max_tries + 1):
        try:
            r = requests.post(
                f"{BASE}/v1/verify/pan",
                headers={"Authorization": f"Bearer {os.environ['STAMPMITRA_API_KEY']}"},
                json=payload,
                timeout=15,
            )
        except requests.RequestException:
            if attempt == max_tries:
                raise
            time.sleep(2 ** attempt * 0.5)
            continue

        if r.ok:
            return r.json()

        try:
            err = r.json().get("error", {})
        except ValueError:
            err = {}
        log.error("stampmitra_error status=%s code=%s requestId=%s",
                  r.status_code, err.get("code"), err.get("requestId"))

        if r.status_code not in RETRYABLE or attempt == max_tries:
            raise StampMitraError(r.status_code, err.get("code"),
                                  err.get("message"), err.get("requestId"))
        time.sleep(2 ** attempt * 0.5 + random.random() * 0.3)

इस code की ख़ास बातें

सिर्फ़ 429 और 502 retry होते हैं। बाकी सब तुरंत StampMitraError बनकर ऊपर जाते हैं, जहाँ आपका business logic तय करता है कि 402 पर क्या दिखाना है। हर failure में requestId log होता है। अगर आप पूरे flow को Node.js और Python में PAN verify वाले लेख से मिलाकर देखना चाहें, तो वह इसी wrapper का दूसरा पहलू है।

requestId और logging: support को क्या भेजें कि जवाब जल्दी मिले?

एक अच्छा incident ticket पाँच मिनट में हल होता है, और अधूरा ticket तीन दिन। फ़र्क बस इतना है कि आपने कौन सी जानकारी साथ भेजी।

support ticket में ये चीज़ें रखिए

1. requestId: सबसे ज़रूरी। एक से ज़्यादा हों तो सब।
2. समय: UTC में, सेकंड तक।
3. Endpoint और method: जैसे POST /v1/verify/pan।
4. Status और error.code।
5. Environment: sandbox (sk_test_) या production (sk_live_)। key का पूरा मान कभी मत भेजिए, सिर्फ़ उसका शुरुआती prefix।
6. आपने क्या बदला था: नया deploy, नई key, नया batch job।

संपर्क के लिए support पेज देखें या [email protected] पर लिखें।

अपने log में क्या रखें, क्या नहीं

रखें: timestamp, endpoint, HTTP status, error.code, requestId, कितनी बार retry हुआ, और आपके अपने business का id (जैसे आवेदन का id)।

मत रखें: पूरी API key, और request का पूरा body। उस body में PAN, खाता संख्या जैसे व्यक्तिगत विवरण होते हैं। इनको log में कच्चा सहेजना अनावश्यक जोखिम है। ज़रूरत हो तो मास्क करके रखिए (जैसे PAN के शुरुआती और आखिरी अक्षर)। अपने product में निजी डेटा की सीमा और अवधि DPDP Act 2023 के अनुसार तय करते समय अपने क़ानूनी सलाहकार से राय लीजिए, यह लेख कोई क़ानूनी सलाह नहीं है।

एक काम की आदत: खुद का correlation id

अपने हर आवेदन या order के लिए अपना id रखिए (जैसे externalOrderId) और log में उसके साथ StampMitra का requestId जोड़िए। तब आप दोनों दिशाओं में खोज सकते हैं: "इस आवेदन की कौन सी call फेल हुई?" और "इस requestId वाली call किस आवेदन की थी?"

alert कैसे बनाएँ

सिर्फ़ "कुल errors" पर alert मत लगाइए। इन्हें अलग रखिए:

• 402 की किसी भी घटना पर तुरंत alert (पैसे का मामला है, एक भी काफी है)।
• 401 या 403 में उछाल पर alert (config टूटा है)।
• 429 पर slow alert (कभी-कभार सामान्य है, लगातार हो तो समस्या)।
• 502 पर प्रतिशत के आधार पर alert।

Billing, referenceId और idempotency: error और "नकारात्मक नतीजे" में उलझन कैसे बचाएँ?

valid: false कोई error नहीं है

यह आम भ्रम है। मान लीजिए आपने एक PAN जाँचा और जवाब आया valid: false। वह HTTP 200 है, error नहीं। reference में साफ़ लिखा है कि सकारात्मक और नकारात्मक दोनों नतीजे पूरे, billable verification हैं। इसलिए:

• अपने "errors" वाले dashboard में इन्हें मत गिनिए।
• इसी तरह found: false (Udyam, PAN से GSTIN जैसे endpoints पर) भी 200 पर आने वाला वैध नतीजा है।
• नकारात्मक नतीजे पर retry करने से आप बस दोबारा पैसे देंगे और वही उत्तर पाएँगे।

referenceId क्या है और क्या नहीं

हर verification response में referenceId आता है, जैसे SMV-20260927-8F42K7 (प्रारूप SMV-YYYYMMDD-XXXXXXX)। यह StampMitra का अपना transaction id है, नकारात्मक नतीजों में भी मौजूद रहता है। पर reference में साफ़ चेतावनी है: यह idempotency key नहीं है। इसे दोबारा भेजकर "वही call" साबित नहीं किया जा सकता। इसे अपने रिकॉर्ड और मिलान (reconciliation) में सहेजिए।

requestId बनाम referenceId

Idempotency-Key: orders और payments के लिए

POST /v1/orders (scope orders.create) और POST /v1/payments/intents (scope payments.write) पर वैकल्पिक Idempotency-Key header है। जब भी आपके पास timeout या अधूरा जवाब हो, इस header के साथ वही अनुरोध दोबारा भेजना सुरक्षित तरीका है। हर नए order के लिए नई unique key रखिए, और timeout पर वही key दोहराइए। इस header के सटीक व्यवहार (कितने समय तक याद रखा जाता है, दोहराने पर क्या लौटता है) का ब्यौरा reference में नहीं दिया गया है, इसलिए उन्हें मानकर न चलें और sandbox में खुद परखें।

हमारे Terms में भी यही अपेक्षा है कि जहाँ API idempotency का समर्थन करे, वहाँ developer उसे लागू करे, ख़ासकर भुगतान और ऐसे संचालन में जो पलटे नहीं जा सकते। e-stamp के पूरे क्रम का वर्णन e-stamp order flow में है।

Errors और सुरक्षा: key, डेटा और user message कैसे संभालें?

errors का संबंध सुरक्षा से सीधा है, क्योंकि गलत समय पर गलत जानकारी बाहर चली जाती है।

API key को ऐसे संभालिए

• key को environment variable या secrets manager में रखिए, code या git में नहीं।
• 401 या 403 की जाँच में debugging के दौरान key को log में print मत कीजिए।
• sandbox (sk_test_) और production (sk_live_) की keys अलग रखिए, और production की key सिर्फ़ production के servers पर।
• संवेदनशील scopes पर IP allowlist लग सकती है (reference में लिखा है कि "sensitive scopes can additionally be restricted to an IP allowlist")। अगर आप अचानक नए सर्वर या नए region से call करने लगें और error आए, तो यह संभावना भी जाँचिए। reference में इसके लिए किसी विशेष status की जानकारी नहीं है, इसलिए पुष्टि के लिए support से पूछिए।
• हमारी सुरक्षा अपेक्षाओं के लिए API security policy देखें।

उपयोगकर्ता को क्या दिखाएँ

निजी डेटा से जुड़ी बातें

सत्यापन के दौरान PAN, खाता संख्या या जन्मतिथि जैसा निजी डेटा आपके सिस्टम से गुज़रता है। सामान्य अच्छी आदतें: उपयोगकर्ता की सहमति लेकर ही जाँच करें, सिर्फ़ उसी उद्देश्य के लिए इस्तेमाल करें जिसके लिए सहमति ली, और ज़रूरत से ज़्यादा समय तक न रखें। error log में यही डेटा चुपके से जमा न हो जाए। स्टैक ट्रेस या exception में पूरा request body न जाने दीजिए। हमारी Developer Privacy Policy और Data Processing Addendum में हमारी तरफ़ की रूपरेखा है, और आपके अपने दायित्व आपके क़ानूनी सलाहकार के साथ तय होने चाहिए।

test में असली डेटा नहीं

error के परीक्षण में असली PAN या Aadhaar मत इस्तेमाल कीजिए। reference में दिए नमूना मान, जैसे PAN ABCDE1234F और GSTIN 07AAAAA1111A1Z1, ही काफी हैं।

Sandbox में errors का परीक्षण और production में जाने से पहले की जाँच

सबसे अच्छा समय यह जानने का कि आपका code 402 या 429 पर क्या करता है, वह आज दोपहर है, रात दो बजे नहीं।

Sandbox में क्या आज़माएँ

StampMitra का sandbox मुफ़्त है, बिना credit card के, और signup के तुरंत बाद आपको sk_test_ key मिल जाती है (quickstart देखें)। इसमें आप ये सब जाँच सकते हैं, जो बिना असली नुकसान के बनाए जा सकते हैं:

1. 401: Authorization header हटाकर या गलत key देकर call कीजिए।
2. 400: PAN की जगह ABC123 भेजिए और error.message देखिए।
3. 403: ऐसी key से दूसरे product का endpoint call कीजिए जिसका scope उसमें न हो।
4. 429: एक छोटी loop में तेज़ calls भेजकर देखें कि आपका backoff कैसे काम करता है। (सावधानी: sandbox की अपनी सीमाएँ हो सकती हैं, इसलिए पहले अपनी सीमा जाँच लें।)
5. नकारात्मक नतीजा: ध्यान से देखिए कि 200 पर valid: false आने पर आपका code इसे error न माने।

402 और 502 को sandbox में जानबूझकर पैदा करना हर खाते के लिए संभव नहीं हो सकता, क्योंकि reference में इनके लिए कोई विशेष test trigger नहीं बताया गया है। इसके लिए अपने code में HTTP client को mock कीजिए और reference के असली body (ऊपर के उदाहरण) लौटाइए। इस तरह unit test भी 402, 429 और 502 के रास्तों को चलाएँगे।

Production से पहले की सूची

• हर status के लिए अलग शाखा है और 401/403 पर retry नहीं होता।
• 429 और 502 पर सीमित backoff है, अंतहीन loop नहीं।
• हर failure में requestId log होता है, पर key और कच्चा PAN नहीं।
• 402 पर तुरंत alert है और wallet balance पर पहले से अलर्ट है।
• valid: false और found: false को error नहीं गिना जाता।
• order/payment की calls में Idempotency-Key है।
• production key सिर्फ़ production environment में है।
• उपयोगकर्ता को दिखने वाले संदेश अंदरूनी जानकारी नहीं खोलते।
• production access की स्वीकृति मिल चुकी है। हमारी Developer Onboarding नीति के अनुसार sandbox का परीक्षण पूरा होना production स्वीकृति की गारंटी नहीं है।

इन सब बातों को sandbox और production keys पर विस्तृत लेख में भी देखा जा सकता है।

Troubleshooting: लक्षण से कारण तक

जब सब कुछ एक साथ गड़बड़ दिखे, तो यह तालिका लक्षण से सबसे संभावित कारण तक पहुँचाने के लिए है।

जब कुछ समझ न आए

तीन चीज़ें इकट्ठा कीजिए: एक असली failed response का requestId, उसका समय, और आपका environment। फिर support या contact से संपर्क कीजिए। एक अच्छा नियम: जब तक requestId न हो, तब तक अटकल मत लगाइए। इसके बिना दो लोग घंटों तक अंदाज़े लगा सकते हैं।

StampMitra आपकी कैसे मदद करता है

StampMitra, Bani Global Industries LLP (LLPIN ACI-6373) द्वारा संचालित एक निजी LegalTech प्लेटफ़ॉर्म है। यह कोई सरकारी संस्था या law firm नहीं है, और इस लेख में कुछ भी क़ानूनी सलाह नहीं है। जो हम आज देते हैं वह यह है।

एक जैसी error शक्ल। StampMitra API की हर error { error: { code, message, requestId } } में आती है, और stack trace या database की कच्ची त्रुटि बाहर नहीं निकलती। इससे आपका client code छोटा और भरोसेमंद रहता है। हर endpoint का असली error body हमारी Verification और e-stamp docs में उदाहरण के रूप में दिया है, और हर product पेज (जैसे PAN) पर आपको उसके खास errors भी दिखते हैं।

साफ़ authentication। हर endpoint Authorization: Bearer या x-api-key से चलता है। keys sandbox और production के लिए अलग होती हैं और scopes से बँधी हैं। authentication docs में पूरा ब्यौरा है।

मुफ़्त sandbox। आप बिना credit card के साइन अप करके तुरंत sk_test_ key पा सकते हैं और अपना error handling ऊपर के तरीके से परख सकते हैं। production के लिए KYC-approved organization चाहिए।

सहायता। किसी भी अटकी हुई स्थिति में requestId के साथ [email protected] पर लिखिए। हमारे Postman collection और SDKs पेज पर तैयार नमूने मिलेंगे, और webhooks पेज पर event-आधारित संचार की जानकारी है।

यदि आपका उपयोग मामला KYC का है, तो फिनटेक और NBFC के लिए KYC API वाला लेख इसी error व्यवहार को एक पूरे onboarding प्रवाह में दिखाता है। PAN की जाँच की शुरुआत के लिए PAN verification API की गाइड देखें।

आगे क्या (योजनाएँ, वादे नहीं)

हम कुछ चीज़ों पर काम करने की सोच रहे हैं: ज़्यादा विस्तृत error codes, rate limit की स्थिति बताने वाले response headers, और sandbox में जानबूझकर 402 या 429 पैदा करने वाले test तरीके। ये अभी उपलब्ध नहीं हैं, इसलिए अपना code आज की स्थिति पर बनाइए, यानी status और code पर branching, और requestId का log।

हम चाहते हैं कि आपको अपने error handling के लिए अटकल न लगानी पड़े। अगर इस लेख में कोई बात आपके अनुभव से अलग दिखे, तो हमें बताइए। सबसे अच्छी जाँच हमेशा आपका अपना sandbox है।

API reference एक नज़र में

{
  "referenceId": "SMV-20260927-8F42K7",
  "pan": "ABCDE1234F",
  "type": "Individual",
  "valid": true,
  "registeredName": "RAHUL KUMAR",
  "fatherName": "SURESH KUMAR",
  "panStatus": "VALID",
  "panStatusCode": "E",
  "panStatusDescription": "Existing and valid PAN",
  "nameMatchResult": "MATCH",
  "nameMatchScore": "100",
  "aadhaarSeedingStatus": "y",
  "aadhaarSeedingStatusDescription": "Aadhaar linked",
  "lastUpdatedAt": "2023-04-01",
  "message": "PAN is Valid"
}

अक्सर पूछे जाने वाले सवाल