गड़बड़ी वाले जवाबों को मैनेज करना

इस गाइड में, Merchant API से मिलने वाली गड़बड़ियों को ठीक करने का तरीका बताया गया है. गड़बड़ी के रिस्पॉन्स के स्ट्रक्चर और उसकी स्थिरता को समझना ज़रूरी है. इससे, इंटिग्रेशन को मज़बूत बनाया जा सकता है. साथ ही, गड़बड़ी होने पर, इंटिग्रेशन अपने-आप ठीक हो सकता है या उपयोगकर्ताओं को काम की जानकारी दी जा सकती है.

खास जानकारी

Merchant API का कोई अनुरोध पूरा न होने पर, एपीआई एक स्टैंडर्ड एचटीटीपी स्टेटस कोड (4xx या 5xx) दिखाता है. साथ ही, JSON फ़ॉर्मैट में एक रिस्पॉन्स बॉडी भी दिखाता है, जिसमें गड़बड़ी के बारे में जानकारी होती है. Merchant API, गड़बड़ी की जानकारी के लिए AIP-193 स्टैंडर्ड का पालन करता है. इससे, मशीन से पढ़ी जा सकने वाली जानकारी मिलती है. इसकी मदद से, आपका ऐप्लिकेशन गड़बड़ी के खास मामलों को प्रोग्राम के ज़रिए ठीक कर सकता है.

गड़बड़ी के रिस्पॉन्स का स्ट्रक्चर

गड़बड़ी का रिस्पॉन्स, JSON फ़ॉर्मैट में एक ऑब्जेक्ट होता है. इसमें code, message, और status जैसे स्टैंडर्ड फ़ील्ड शामिल होते हैं. अहम बात यह है कि इसमें details कलेक्शन भी शामिल होता है. गड़बड़ियों को प्रोग्राम के ज़रिए ठीक करने के लिए, आपको details में मौजूद किसी ऐसे ऑब्जेक्ट को देखना चाहिए जिसमें @type की वैल्यू type.googleapis.com/google.rpc.ErrorInfo हो.

ErrorInfo ऑब्जेक्ट में, गड़बड़ी के बारे में स्थिर और स्ट्रक्चर्ड डेटा होता है:

• डोमेन: गड़बड़ी का लॉजिकल ग्रुप. आम तौर पर, यह merchantapi.googleapis.com होता है.
• metadata: गड़बड़ी से जुड़ी डाइनैमिक वैल्यू का मैप. इसमें ये शामिल हैं:
  • REASON: गड़बड़ी की सटीक जानकारी देने वाला, स्थिर आइडेंटिफ़ायर. उदाहरण के लिए, INVALID_NAME_PART_NOT_NUMBER, PERMISSION_DENIED_ACCOUNTS). यह फ़ील्ड हमेशा मौजूद होता है. अपने ऐप्लिकेशन लॉजिक में, गड़बड़ी को ठीक करने के लिए इस फ़ील्ड का इस्तेमाल करें.
  • HELP_CENTER_LINK: समस्या को ठीक करने के लिए, ज़्यादा जानकारी और निर्देश देता है. यह फ़ील्ड, सभी गड़बड़ियों के लिए मौजूद नहीं होता. हालांकि, हमारा प्लान है कि आने वाले समय में, उन गड़बड़ियों के लिए इसे उपलब्ध कराया जाए जिनके लिए ज़्यादा जानकारी की ज़रूरत हो सकती है.
  • अन्य डाइनैमिक फ़ील्ड: अन्य कुंजियां, जो संदर्भ देती हैं. जैसे, अमान्य फ़ील्ड का नाम (FIELD_LOCATION) या वह वैल्यू जिसकी वजह से गड़बड़ी हुई (FIELD_VALUE).

गड़बड़ी के रिस्पॉन्स के उदाहरण

यहां JSON फ़ॉर्मैट में, Merchant API की गड़बड़ी का एक उदाहरण दिया गया है. इसमें, संसाधन का नाम गलत फ़ॉर्मैट में दिया गया था.

{
  "error": {
    "code": 400,
    "message": "[name] The part `account` of the resource name in field `name` must be a number, but has value: `abcd`.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "VARIABLE_NAME": "account",
          "FIELD_LOCATION": "name",
          "FIELD_VALUE": "abcd",
          "REASON": "INVALID_NAME_PART_NOT_NUMBER"
        }
      }
    ]
  }
}

यहां पुष्टि करने में गड़बड़ी का एक उदाहरण दिया गया है:

{
  "error": {
    "code": 401,
    "message": "The caller does not have access to the accounts: [1234567]",
    "status": "UNAUTHENTICATED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "unauthorized",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_IDS": "[1234567]",
          "REASON": "PERMISSION_DENIED_ACCOUNTS"
        }
      }
    ]
  }
}

गड़बड़ी के फ़ील्ड की स्थिरता

गड़बड़ी को ठीक करने का लॉजिक लिखते समय, यह जानना ज़रूरी है कि किन फ़ील्ड पर भरोसा किया जा सकता है और किन में बदलाव हो सकता है.

• स्थिर फ़ील्ड:

• details.metadata.REASON: गड़बड़ी का सटीक आइडेंटिफ़ायर. आपको अपने ऐप्लिकेशन के कंट्रोल फ़्लो लॉजिक के लिए इस फ़ील्ड पर भरोसा करना चाहिए.

  • details.metadata कुंजियां: मेटाडेटा मैप में मौजूद कुंजियां (उदाहरण के लिए, FIELD_LOCATION, ACCOUNT_IDS) स्थिर होती हैं.
  • code: हाई-लेवल एचटीटीपी स्टेटस कोड (उदाहरण के लिए, 400, 401, 503) स्थिर होता है.

• अस्थिर फ़ील्ड:

  • message: गड़बड़ी का वह मैसेज जिसे इंसान पढ़ सकते हैं, स्थिर नहीं होता. यह सिर्फ़ डेवलपर के डीबग करने के लिए होता है. ऐसा कोड न लिखें जो पार्स करता हो या message फ़ील्ड के टेक्स्ट कॉन्टेंट पर निर्भर करता हो. ऐसा इसलिए, क्योंकि साफ़ तौर पर जानकारी देने या संदर्भ जोड़ने के लिए, इसमें बिना सूचना दिए बदलाव किया जा सकता है.
  • details.metadata वैल्यू: कुंजियां स्थिर होती हैं, लेकिन जानकारी देने वाली कुंजियों की वैल्यू में बदलाव हो सकता है. उदाहरण के लिए, अगर HELP_CENTER_LINK कुंजी दी जाती है, तो हो सकता है कि इससे जुड़े यूआरएल को, पहले से सूचना दिए बिना, दस्तावेज़ के नए पेज पर अपडेट कर दिया जाए. हालांकि, जैसा कि पहले बताया गया है, details.metadata.REASON की वैल्यू स्थिर होती है.

सबसे सही तरीके

यह पक्का करने के लिए कि आपका इंटिग्रेशन, गड़बड़ियों को आसानी से ठीक कर सके, इन सबसे सही तरीकों को अपनाएं.

लॉजिक के लिए details.metadata.REASON का इस्तेमाल करना

गड़बड़ी की वजह जानने के लिए, हमेशा metadata मैप में मौजूद REASON का इस्तेमाल करें. सिर्फ़ एचटीटीपी स्टेटस कोड पर भरोसा न करें, क्योंकि कई गड़बड़ियों के लिए एक ही स्टेटस कोड हो सकता है.

गड़बड़ी के मैसेज को पार्स न करना

स्थिरता वाले सेक्शन में बताया गया है कि message फ़ील्ड, इंसानों के लिए होता है. अगर आपको डाइनैमिक जानकारी चाहिए (जैसे, कौनसे फ़ील्ड में गड़बड़ी हुई), तो उसे metadata मैप से निकालें. इसके लिए, FIELD_LOCATION, VARIABLE_NAME जैसी स्थिर कुंजियों का इस्तेमाल करें.

एक्स्पोनेंशियल बैकऑफ़ लागू करना

ऐसी गड़बड़ियों के लिए जो अस्थायी तौर पर सेवा उपलब्ध न होने या अनुरोध संख्या सीमित करने की वजह से होती हैं, एक्स्पोनेंशियल बैकऑफ़ की रणनीति लागू करें. इसका मतलब है कि फिर से कोशिश करने से पहले, कुछ समय के लिए इंतज़ार करना. साथ ही, हर बार गड़बड़ी होने पर, इंतज़ार का समय बढ़ाना.

• quota/request_rate_too_high: इस गड़बड़ी का मतलब है कि आपने किसी खास कोटा ग्रुप के लिए, मिनट के हिसाब से तय कोटा पार कर लिया है. अनुरोध दर कम करें.
• internal_error: आम तौर पर, ये गड़बड़ियां अस्थायी होती हैं. एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करें.

Merchant API की सहायता टीम से संपर्क करने का तरीका

अगर आपको किसी गड़बड़ी के बारे में Merchant API की सहायता टीम से संपर्क करना है, तो अपने अनुरोध में यह जानकारी दें:

1. गड़बड़ी का सटीक रिस्पॉन्स
2. एपीआई के तरीके का नाम
3. अनुरोध का पेलोड
4. टाइमस्टैंप या वह समयावधि जिसके दौरान, तरीके को कॉल किया गया था और गड़बड़ियां मिली थीं