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

इस गाइड में, 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 ऑब्जेक्ट, गड़बड़ी के बारे में स्ट्रक्चर्ड डेटा उपलब्ध कराता है:

  • domain: गड़बड़ी का लॉजिकल ग्रुप, आम तौर पर merchantapi.googleapis.com.
  • मेटाडेटा: गड़बड़ी से जुड़ी डाइनैमिक वैल्यू का मैप. इसमें ये शामिल हैं:
    • 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: ये आम तौर पर कुछ समय के लिए होते हैं. एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करें. ध्यान दें: अगर बैकऑफ़ के साथ कई बार फिर से कोशिश करने के बाद भी internal_error की समस्या बनी रहती है, तो Merchant API की सहायता टीम से संपर्क करने का तरीका देखें.

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

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

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