त्रुटियाँ

Partner API यह बताने के लिए कि कोई अनुरोध क्यों विफल हुआ, मानक HTTP स्टेटस कोड और JSON रिस्पॉन्स बॉडी का उपयोग करता है।

त्रुटि रिस्पॉन्स का स्वरूप

अधिकांश API त्रुटियाँ एक संदेश और, जहाँ उपलब्ध हो, संरचित विवरण वाली JSON बॉडी लौटाती हैं।

{
  "success": false,
  "message": "Request body.members[0].member_id is required"
}

कुछ डोमेन-विशिष्ट एंडपॉइंट एक स्पष्ट स्टेटस और कारण लौटाते हैं। उदाहरण के लिए, एक्सेस-कंट्रोल विफलताओं में reason, door_id, facility_id और event_id जैसे फ़ील्ड शामिल होते हैं।

{
  "status": "failed",
  "reason": "device_offline",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_id": "00000000-0000-0000-0000-000000000045"
}

स्टेटस कोड

400 Bad Request

अनुरोध गलत तरीके से बना है या उसमें आवश्यक फ़ील्ड नहीं हैं। पुनः प्रयास करने से पहले अनुरोध ठीक करें।

401 Unauthorized

प्रमाणीकरण विफल रहा। जाँचें कि आप अपनी API सीक्रेट कुंजी को यूज़रनेम और खाली पासवर्ड के साथ HTTP Basic Auth का उपयोग कर रहे हैं।

403 Forbidden

कुंजी मान्य है, लेकिन ऑपरेशन की अनुमति नहीं है। सामान्य कारणों में राइट ऑपरेशन के लिए read-only कुंजी का उपयोग करना या ऐसी सुविधा तक पहुँचने का प्रयास करना शामिल है जहाँ आपका इंटीग्रेशन सक्षम नहीं है।

404 Not Found

अनुरोधित संसाधन नहीं मिला या आपके इंटीग्रेशन के लिए उपलब्ध नहीं है।

409 Conflict

अनुरोध संसाधन की वर्तमान स्थिति से टकराता है। एक्सेस कंट्रोल के लिए, इसमें किसी Door/Gate Controller का मेंटेनेंस मोड में होना शामिल हो सकता है।

422 Unprocessable Entity

अनुरोध मान्य JSON है, लेकिन सिमेंटिक सत्यापन में विफल रहता है। पुनः प्रयास करने से पहले डेटा ठीक करें।

429 Too Many Requests

इंटीग्रेशन ने प्रलेखित रेट लिमिट पार कर दी है। एक्सपोनेंशियल बैकऑफ़ के साथ पुनः प्रयास करें।

500 Internal Server Error

किसी आंतरिक त्रुटि के कारण Performance Hub अनुरोध पूरा नहीं कर सका। बैकऑफ़ के साथ पुनः प्रयास करें। यदि समस्या बनी रहती है, तो एंडपॉइंट, टाइमस्टैम्प और रिस्पॉन्स बॉडी के साथ सहायता से संपर्क करें।

503 Service Unavailable

कोई निर्भर सेवा या डिवाइस उपलब्ध नहीं है। Door/Gate Controller अनलॉक के लिए, इसका अर्थ हो सकता है कि कंट्रोलर ऑफ़लाइन है।

504 Gateway Timeout

ऑपरेशन का समय समाप्त हो गया। Door/Gate Controller अनलॉक के लिए, इसका अर्थ है कि टाइमआउट अवधि से पहले अनलॉक की पुष्टि नहीं हुई।

Access Time Window विफलताएँ

अमान्य स्नैपशॉट लिखे जाने से पहले ही विंडो सत्यापन विफल हो जाता है। पुनः प्रयास न किए जा सकने वाले सामान्य कारणों में शामिल हैं:

• access_time_windows मौजूद होने पर access_time_windows_revision का न होना।
• स्ट्रिंग, फ़्लोटिंग-पॉइंट, या संभवतः मिलीसेकंड वाले epoch मान।
• अमान्य IANA टाइमज़ोन, उलटा अंतराल, डुप्लिकेट external_id, ओवरलैप होते साप्ताहिक ब्लॉक, या ऐसा रात भर का ब्लॉक जिसे विभाजित नहीं किया गया।
• प्रलेखित संख्या, लंबाई या अवधि सीमाओं से बाहर का मान।

अलग सामान्यीकृत सामग्री के साथ दोहराया गया रिविज़न 409 Conflict होता है। नवीनतम आधिकारिक स्थिति से मिलान करें और एक नया रिविज़न आवंटित करें; टकराव वाली जोड़ी को बार-बार पुनः प्रयास न करें। पुराने रिविज़न को नई स्थिति को ओवरराइट करने देने के बजाय छोड़े गए पुराने (stale) स्नैपशॉट के रूप में रिपोर्ट किया जाता है। अज्ञात या मैप न किया गया scope_key प्राधिकरण के लिए बंद अवस्था में विफल (fail closed) होता है और इसे कॉन्फ़िगरेशन अलर्ट माना जाना चाहिए।

यदि डिलीवरी का समय समाप्त हो जाता है या अस्थायी 5xx प्राप्त होता है, तो उसी रिविज़न के साथ ठीक वही सामान्यीकृत स्नैपशॉट पुनः भेजें। यदि अपस्ट्रीम स्रोत फ़ेच विफल हुआ है, तो विंडो फ़ील्ड को पूरी तरह छोड़ दें; उसकी जगह कभी भी खाली ऐरे न भेजें।

पुनः प्रयास संबंधी मार्गदर्शन

इन्हें सीमित एक्सपोनेंशियल बैकऑफ़ के साथ पुनः प्रयास करें:

• 429
• 500
• 502
• 503
• 504

इन्हें बिना सोचे-समझे पुनः प्रयास न करें:

• 400
• 401
• 403
• 404
• 409
• 422

एक्सेस कंट्रोल के लिए, टाइमआउट और ऑफ़लाइन रिस्पॉन्स को हमेशा विफल अनलॉक मानें, जब तक कि आपके अपने एक्सेस नियम और सुरक्षा प्रक्रियाएँ कुछ और न कहें।

सहायता के लिए शामिल किए जाने वाले विवरण

सहायता से संपर्क करते समय, ये शामिल करें:

• एंडपॉइंट और HTTP मेथड।
• टाइमस्टैम्प और टाइमज़ोन।
• पार्टनर कुंजी ID, सीक्रेट कुंजी नहीं।
• उपयोग किया गया सुविधा पहचानकर्ता।
• आपके सिस्टम का स्रोत रिकॉर्ड ID।
• रिस्पॉन्स स्टेटस और बॉडी।
• जहाँ उपलब्ध हो, event_id या command_id।