त्रुटि कोड
यह पृष्ठ त्रुटि प्रबंधन के लिए एकल सत्य का स्रोत है। SDK-विशिष्ट त्रुटि कोड प्रत्येक SDK के Error handling पृष्ठ में documented हैं; यह पृष्ठ API contract स्तर पर त्रुटियों को कवर करता है।
HTTP status codes
| Code | अर्थ | कहाँ लागू होता है |
|---|---|---|
200 OK | अनुरोध सफल। | सभी contracts। |
201 Created | Resource बनाया गया (दुर्लभ; अधिकांश creations 200 लौटाती हैं)। | API contract। |
400 Bad Request | Payload अनुचित है या आवश्यक फ़ील्ड अनुपस्थित हैं। Body समस्याग्रस्त फ़ील्ड की पहचान करती है। | सभी contracts। |
401 Unauthorized | प्रमाणीकरण अनुपस्थित, समाप्त, या अमान्य। | सभी contracts। |
403 Forbidden | प्रमाणीकरण मान्य है लेकिन tenant अनुरोधित resource के लिए सक्षम नहीं है (जैसे, आपके APIKEY में न हो किसी capability को call करना)। | Web & SDK, API। |
404 Not Found | Resource मौजूद नहीं है या प्रमाणित tenant से संबंधित नहीं है। | सभी contracts। |
409 Conflict | Resource मौजूद है लेकिन इस operation के लिए सही state में नहीं है (जैसे, अभी भी प्रोसेस हो रही प्रक्रिया से दस्तावेज़ fetch करना)। | Web & SDK, API। |
410 Gone | Resource मौजूद था लेकिन retention policy के अनुसार हटा दिया गया (document fetch endpoints), या प्रक्रिया मौजूद है लेकिन त्रुटि स्थिति में समाप्त हुई — देखें Get Process। | Document fetch endpoints; API Get Process। |
429 Too Many Requests | आप rate limit से टकराए। Exponential backoff के साथ पुनः प्रयास करें। | सभी contracts। |
5xx | Platform त्रुटि। Backoff के साथ पुनः प्रयास करें; यदि लगातार हो, तो response body और timestamp के साथ support से संपर्क करें। | सभी contracts। |
प्रमाणीकरण त्रुटियाँ (401)
| कारण | लक्षण |
|---|---|
| गलत private key (गलत key से sign किया गया assertion) | 401, Authentication failed (1.2.21) |
aud वातावरण URL से मेल नहीं खाता | 401 |
exp claim भूतकाल में | 401, Authentication failed |
असमर्थित algorithm (RS256 का उपयोग करें) | 401 |
| मिश्रित sandbox / production credentials | 401, भले ही credentials सही दिखें |
APIKEY header अनुपस्थित (केवल API contract) | 401 |
अमान्य x-api-key (केवल Magic Link) | 401 |
पूर्ण troubleshooting checklist के लिए Authentication > Common errors देखें।
Capability-स्तरीय outcomes (200 नकारात्मक परिणाम के साथ)
200 OK का मतलब यह नहीं है कि उपयोगकर्ता सत्यापन में उत्तीर्ण हुआ — इसका मतलब है कि प्लेटफ़ॉर्म ने काम पूरा किया। उपयोगकर्ता-सामना करने वाला निर्णय HTTP status में नहीं, बल्कि response body में रहता है:
| फ़ील्ड | नकारात्मक मान | कहाँ दिखाई देता है |
|---|---|---|
process.result | PROCESS_RESULT_FAILED | Web & SDK |
process.authenticationInfo.livenessResult | NO | Web & SDK |
liveness | 2 | API |
unicoId.result | no | API |
data.result.status | not_verified | Magic Link |
Retry नीति
| Status | पुनः प्रयास करना चाहिए? | कैसे |
|---|---|---|
5xx | हाँ | Exponential backoff (1s, 2s, 4s, 8s, …)। 5 प्रयासों पर cap करें। |
429 | हाँ | यदि मौजूद हो तो Retry-After header का सम्मान करें; अन्यथा exponential backoff। |
4xx (अन्य) | नहीं | अनुरोध गलत है। पुनः प्रयास करने से पहले input ठीक करें। |
401 | Conditionally | access token एक बार refresh करें। यदि नया अनुरोध भी 401 लौटाता है, तो समस्या structural है — पुनः प्रयास न करें। |
IDCloud प्लेटफ़ॉर्म वर्तमान में creation endpoints पर idempotency-key mechanism उजागर नहीं करता। POST /client/v1/process या POST /processes/v1 को पुनः प्रयास करते समय सावधान रहें — 5xx पर network त्रुटि वास्तव में server-side सफल हो सकती है, और पुनः प्रयास एक duplicate प्रक्रिया बनाएगा। संदेह होने पर, पुनः प्रयास करने से पहले अपने internal correlation ID द्वारा recent प्रक्रियाएँ पुनः प्राप्त करें।
SDK त्रुटियाँ कहाँ रहती हैं
Web SDK, Android SDK, iOS SDK और Flutter SDK के त्रुटि catalogs प्रत्येक SDK के समर्पित Error handling पृष्ठ में documented हैं:
- Web SDK > Error handling
- Android SDK > Error handling
- iOS SDK > Error handling
- Flutter SDK > Error handling
ये device-side त्रुटियों को कवर करते हैं (camera permission अस्वीकृत, capture timeout, device पर network अनुपलब्ध) — यहाँ documented API-side त्रुटियों से अलग।