एपीआई से जुड़ी गड़बड़ियों को समझना

इस गाइड में बताया गया है कि Google Ads API, गड़बड़ियों को कैसे मैनेज करता है और उनकी जानकारी कैसे देता है. एपीआई से जुड़ी गड़बड़ियों के स्ट्रक्चर और उनके मतलब को समझना ज़रूरी है. इससे ऐसे मज़बूत ऐप्लिकेशन बनाए जा सकते हैं जो अमान्य इनपुट से लेकर सेवा के अस्थायी तौर पर उपलब्ध न होने जैसी समस्याओं को आसानी से हल कर सकते हैं.

Google Ads API, Google API के स्टैंडर्ड गड़बड़ी मॉडल का पालन करता है. यह gRPC स्टेटस कोड पर आधारित है. गड़बड़ी की वजह से मिले हर एपीआई जवाब में, Status ऑब्जेक्ट शामिल होता है. इसमें ये चीज़ें होती हैं:

• यह संख्या के तौर पर गड़बड़ी का कोड है.
• गड़बड़ी का मैसेज.
• गड़बड़ी के बारे में ज़्यादा जानकारी (ज़रूरी नहीं).

कैननिकल से जुड़ी गड़बड़ी के कोड

Google Ads API, gRPC और HTTP की ओर से तय किए गए कैननिकल गड़बड़ी कोड के सेट का इस्तेमाल करता है. इन कोड से, गड़बड़ी के टाइप के बारे में खास जानकारी मिलती है. समस्या की बुनियादी वजह जानने के लिए, आपको हमेशा इस संख्या वाले कोड की जांच करनी चाहिए.

यहां दी गई टेबल में, Google Ads API का इस्तेमाल करते समय दिखने वाले सबसे सामान्य कोड के बारे में खास जानकारी दी गई है:

gRPC कोड	एचटीटीपी कोड	Enum का नाम	ब्यौरा	दिशा-निर्देश
0	200	OK	कोई गड़बड़ी नहीं है; इससे पता चलता है कि कार्रवाई पूरी हो गई है.	लागू नहीं
1	499	CANCELLED	कार्रवाई रद्द कर दी गई थी. आम तौर पर, ऐसा क्लाइंट करता है.	इसका आम तौर पर मतलब है कि क्लाइंट ने इंतज़ार करना बंद कर दिया है. क्लाइंट-साइड पर टाइम आउट की जांच करें.
2	500	UNKNOWN	कोई अज्ञात गड़बड़ी हुई. गड़बड़ी के मैसेज या जानकारी में ज़्यादा जानकारी मौजूद हो सकती है.	इसे सर्वर की गड़बड़ी के तौर पर माना जाता है. बैकऑफ़ के साथ अक्सर फिर से कोशिश की जा सकती है.
3	400	INVALID_ARGUMENT	क्लाइंट ने एक अमान्य तर्क बताया. इससे ऐसी समस्या का पता चलता है जिसकी वजह से एपीआई, अनुरोध को प्रोसेस नहीं कर पाता. जैसे, गलत तरीके से बनाया गया रिसॉर्स का नाम या अमान्य वैल्यू.	क्लाइंट की गड़बड़ी: अपने अनुरोध के पैरामीटर की समीक्षा करें और पक्का करें कि वे एपीआई की ज़रूरी शर्तों को पूरा करते हों. गड़बड़ी की जानकारी से आम तौर पर यह पता चलता है कि कौनसा तर्क अमान्य था और क्यों. अनुरोध को ठीक करने के लिए, इस जानकारी का इस्तेमाल करें. अनुरोध में सुधार किए बिना, फिर से कोशिश न करें.
4	504	DEADLINE_EXCEEDED	कार्रवाई पूरी होने से पहले ही समयसीमा खत्म हो गई.	सर्वर की गड़बड़ी: अक्सर कुछ समय के लिए होती है. एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करें.
5	404	NOT_FOUND	अनुरोध की गई कुछ इकाइयां, जैसे कि कैंपेन या विज्ञापन ग्रुप नहीं मिला.	क्लाइंट की गड़बड़ी: जिन संसाधनों को ऐक्सेस करने की कोशिश की जा रही है उनकी मौजूदगी और आईडी की पुष्टि करें. गड़बड़ी ठीक किए बिना फिर से कोशिश न करें.
6	409	ALREADY_EXISTS	क्लाइंट ने जिस इकाई को बनाने की कोशिश की है वह पहले से मौजूद है.	क्लाइंट की गड़बड़ी: डुप्लीकेट संसाधन न बनाएं. संसाधन बनाने की कोशिश करने से पहले, देखें कि वह मौजूद है या नहीं.
7	403	PERMISSION_DENIED	कॉलर के पास, तय की गई कार्रवाई को पूरा करने की अनुमति नहीं है.	क्लाइंट की गड़बड़ी: Google Ads खाते के लिए, पुष्टि, अनुमति, और उपयोगकर्ता की भूमिकाओं की जांच करें. अनुमतियों से जुड़ी समस्या हल किए बिना, फिर से कोशिश न करें.
8	429	RESOURCE_EXHAUSTED	ऐसा तब होता है, जब कोई संसाधन खत्म हो गया हो. उदाहरण के लिए, आपने अपना कोटा पूरा कर लिया हो या सिस्टम ओवरलोड हो गया हो.	क्लाइंट/सर्वर से जुड़ी गड़बड़ी: आम तौर पर, इसके लिए इंतज़ार करना पड़ता है. एक्स्पोनेंशियल बैकऑफ़ लागू करें और अनुरोध की दर को कम करें. एपीआई के लिए तय सीमाएं और कोटा देखें.
9	400	FAILED_PRECONDITION	इस कार्रवाई को अस्वीकार कर दिया गया है, क्योंकि सिस्टम उस स्थिति में नहीं है जिसमें कार्रवाई को पूरा किया जा सकता है. उदाहरण के लिए, कोई ज़रूरी फ़ील्ड मौजूद नहीं है.	क्लाइंट की गड़बड़ी: अनुरोध मान्य है, लेकिन state गलत है. प्रीकंडिशन पूरी न होने की वजह जानने के लिए, गड़बड़ी की जानकारी देखें. राज्य की जानकारी ठीक किए बिना, फिर से कोशिश न करें.
10	409	ABORTED	कार्रवाई को रोक दिया गया है. आम तौर पर, ऐसा एक साथ कई अनुरोध मिलने की वजह से होता है. जैसे, लेन-देन में टकराव.	सर्वर की गड़बड़ी: कुछ समय बाद फिर से कोशिश करना आम तौर पर सुरक्षित होता है.
11	400	OUT_OF_RANGE	मान्य सीमा से ज़्यादा वैल्यू डालने की कोशिश की गई.	क्लाइंट की गड़बड़ी: रेंज या इंडेक्स को ठीक करें.
12	501	UNIMPLEMENTED	यह कार्रवाई, एपीआई के ज़रिए लागू नहीं की गई है या एपीआई इसे सपोर्ट नहीं करता.	क्लाइंट की गड़बड़ी: एपीआई वर्शन और उपलब्ध सुविधाओं की जांच करें. फिर से कोशिश न करें.
13	500	INTERNAL	कोई आंतरिक गड़बड़ी हुई. यह सर्वर-साइड की समस्याओं के लिए एक सामान्य सीआर है.	सर्वर से जुड़ी गड़बड़ी: आम तौर पर, एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश की जा सकती है. अगर समस्या बनी रहती है, तो इसकी शिकायत करें.
14	503	UNAVAILABLE	फ़िलहाल, सेवा उपलब्ध नहीं है. यह समस्या कुछ समय के लिए हो सकती है.	सर्वर की गड़बड़ी: हमारा सुझाव है कि आप एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करें.
15	500	DATA_LOSS	डेटा को वापस नहीं पाया जा सकता या डेटा खराब हो गया.	सर्वर की गड़बड़ी: कभी-कभी. इससे किसी गंभीर समस्या का पता चलता है. फिर से कोशिश न करें. अगर समस्या बनी रहती है, तो इसकी शिकायत करें.
16	401	UNAUTHENTICATED	अनुरोध में पुष्टि करने के मान्य क्रेडेंशियल नहीं हैं.	क्लाइंट की गड़बड़ी: अपने पुष्टि करने वाले टोकन और क्रेडेंशियल की पुष्टि करें. पुष्टि की समस्या ठीक किए बिना, फिर से कोशिश न करें.

इन कोड के बारे में ज़्यादा जानने के लिए, एपीआई डिज़ाइन गाइड - गड़बड़ी के कोड देखें.

गड़बड़ी की जानकारी समझना

टॉप-लेवल कोड के अलावा, Google Ads API, Status ऑब्जेक्ट के details फ़ील्ड में गड़बड़ी के बारे में ज़्यादा जानकारी देता है. इस फ़ील्ड में अक्सर GoogleAdsFailure प्रोटो होता है. इसमें अलग-अलग GoogleAdsError ऑब्जेक्ट की सूची शामिल होती है.

हर GoogleAdsFailure ऑब्जेक्ट में ये शामिल हैं:

• errors: GoogleAdsError ऑब्जेक्ट की सूची. इसमें हर ऑब्जेक्ट में, हुई किसी गड़बड़ी की जानकारी दी जाती है.
• request_id: अनुरोध के लिए यूनीक आईडी. यह डीबग करने और सहायता पाने के लिए काम आता है.

हर GoogleAdsError ऑब्जेक्ट ये जानकारी देता है:

• errorCode: यह Google Ads API से जुड़ा ज़्यादा जानकारी वाला गड़बड़ी कोड होता है. जैसे, AuthenticationError.NOT_ADS_USER.
• message: इसमें गड़बड़ी के बारे में ऐसी जानकारी होती है जिसे आसानी से पढ़ा जा सकता है.
• trigger: वह वैल्यू जिसकी वजह से गड़बड़ी हुई. हालांकि, यह जानकारी सिर्फ़ तब दिखती है, जब लागू हो.
• location: इससे पता चलता है कि अनुरोध में गड़बड़ी कहां हुई है. इसमें फ़ील्ड के पाथ भी शामिल होते हैं.
• details: गड़बड़ी के बारे में ज़्यादा जानकारी. जैसे, पब्लिश न होने की वजहें.

गड़बड़ी की जानकारी का उदाहरण

गड़बड़ी होने पर, आपकी क्लाइंट लाइब्रेरी से आपको यह जानकारी मिलेगी. उदाहरण के लिए, INVALID_ARGUMENT (कोड 3) में GoogleAdsFailure की जानकारी इस तरह हो सकती है:

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v17.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ]
    }
  ]
}

इस उदाहरण में, सबसे ऊपर के लेवल के INVALID_ARGUMENT के बावजूद, GoogleAdsFailure की जानकारी से पता चलता है कि name और description फ़ील्ड की वजह से समस्या हुई है. साथ ही, यह भी पता चलता है कि ऐसा क्यों हुआ (REQUIRED और TOO_SHORT).

गड़बड़ी की जानकारी ढूंढना

गड़बड़ी की जानकारी को ऐक्सेस करने का तरीका इस बात पर निर्भर करता है कि स्टैंडर्ड एपीआई कॉल, कुछ अनुरोध पूरे न होने या स्ट्रीमिंग का इस्तेमाल किया जा रहा है या नहीं.

स्टैंडर्ड और स्ट्रीमिंग एपीआई कॉल

जब एपीआई कॉल, आंशिक गड़बड़ी का इस्तेमाल किए बिना फ़ेल हो जाता है, तो स्ट्रीमिंग कॉल सहित, GoogleAdsFailure ऑब्जेक्ट को gRPC रिस्पॉन्स हेडर में ट्रेलिंग मेटाडेटा के हिस्से के तौर पर दिखाया जाता है. अगर स्टैंडर्ड कॉल के लिए REST का इस्तेमाल किया जा रहा है, तो एचटीटीपी रिस्पॉन्स में GoogleAdsFailure दिखता है. क्लाइंट लाइब्रेरी आम तौर पर, इसे GoogleAdsFailure एट्रिब्यूट के साथ अपवाद के तौर पर दिखाती हैं.

कुछ फ़ाइलों का फ़ॉर्मैट नहीं बदला जा सका

अगर partial failure का इस्तेमाल किया जा रहा है, तो फ़ेल हुए ऑपरेशन से जुड़ी गड़बड़ियों को रिस्पॉन्स के partial_failure_error फ़ील्ड में दिखाया जाता है. इन्हें रिस्पॉन्स हेडर में नहीं दिखाया जाता. इस मामले में, GoogleAdsFailure को जवाब में मौजूद google.rpc.Status ऑब्जेक्ट में एम्बेड किया जाता है.

बैच जॉब

बैच प्रोसेसिंग के लिए, अलग-अलग कार्रवाइयों से जुड़ी गड़बड़ियों का पता लगाया जा सकता है. इसके लिए, नौकरी पूरी होने के बाद बैच जॉब के नतीजे वापस पाएं. अगर कोई कार्रवाई पूरी नहीं होती है, तो उसके नतीजे में status फ़ील्ड शामिल होगा. इसमें गड़बड़ी की जानकारी होगी.

अनुरोध का आईडी

request-id एक यूनीक स्ट्रिंग है. इससे आपके एपीआई अनुरोध की पहचान होती है. साथ ही, गड़बड़ी ठीक करने के लिए यह ज़रूरी है.

आपको request-id कई जगहों पर मिल सकता है:

• GoogleAdsFailure: अगर कोई एपीआई कॉल पूरा नहीं होता है और GoogleAdsFailure दिखता है, तो इसमें request_id शामिल होगा.
• ट्रेलिंग मेटाडेटा: अनुरोध पूरा होने और पूरा न होने, दोनों ही स्थितियों में request-id gRPC जवाब के ट्रेलिंग मेटाडेटा में उपलब्ध होता है.
• रिस्पॉन्स हेडर: अनुरोध पूरा होने और पूरा न होने, दोनों ही मामलों में request-id, gRPC और एचटीटीपी रिस्पॉन्स हेडर में भी उपलब्ध होता है. हालांकि, अनुरोध पूरा होने पर स्ट्रीमिंग के लिए किए गए अनुरोधों में यह उपलब्ध नहीं होता.
• SearchGoogleAdsStreamResponse: स्ट्रीमिंग के अनुरोधों के लिए, हर SearchGoogleAdsStreamResponse मैसेज में request_id फ़ील्ड होता है.

गड़बड़ियों की जानकारी लॉग करते समय या सहायता टीम से संपर्क करते समय, request-id को शामिल करना न भूलें. इससे समस्याओं का पता लगाने में मदद मिलती है.

गड़बड़ियों को ठीक करने के सबसे सही तरीके

भरोसेमंद ऐप्लिकेशन बनाने के लिए, यहां दिए गए सबसे सही तरीके अपनाएं:

1. गड़बड़ी की जानकारी देखें: Status ऑब्जेक्ट के details फ़ील्ड को हमेशा पार्स करें. खास तौर पर, GoogleAdsFailure को देखें. GoogleAdsError में मौजूद errorCode, message, और location से, डीबग करने और उपयोगकर्ताओं के सुझाव/राय या शिकायत के लिए सबसे ज़्यादा काम की जानकारी मिलती है.

2. क्लाइंट और सर्वर की गड़बड़ियों में अंतर करें:

   • क्लाइंट की गड़बड़ियां: INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED जैसे कोड. इनके लिए, अनुरोध में बदलाव करने या आपके ऐप्लिकेशन की स्थिति/क्रेडेंशियल में बदलाव करने की ज़रूरत होती है. समस्या को ठीक किए बिना, अनुरोध को फिर से न भेजें.
   • सर्वर से जुड़ी गड़बड़ियां: UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN जैसे कोड. इनसे पता चलता है कि एपीआई सेवा में कुछ समय के लिए समस्या आई है.

3. फिर से कोशिश करने की रणनीति लागू करें:

   • फिर से कोशिश कब करें: सर्वर की कुछ समय के लिए होने वाली गड़बड़ियों के लिए, सिर्फ़ तब फिर से कोशिश करें, जब गड़बड़ी UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN, और ABORTED जैसी हो.
   • एक्सपोनेंशियल बैकऑफ़: फिर से कोशिश करने के बीच बढ़ते समय के लिए, एक्सपोनेंशियल बैकऑफ़ एल्गोरिदम का इस्तेमाल करें. इससे पहले से ही दबाव में चल रही सेवा पर और दबाव नहीं पड़ता. उदाहरण के लिए, पहले एक सेकंड, फिर दो सेकंड, फिर चार सेकंड तक इंतज़ार करें. इसके बाद, फिर से कोशिश करने की ज़्यादा से ज़्यादा संख्या या इंतज़ार करने का कुल समय खत्म होने तक इंतज़ार करें.
   • जिटर: बैकऑफ़ में होने वाली देरी में थोड़ी सी रैंडम रकम जोड़ें, ताकि "थंडरिंग हर्ड" की समस्या को रोका जा सके. इस समस्या में कई क्लाइंट एक साथ फिर से कोशिश करते हैं.

4. पूरी जानकारी लॉग करें: गड़बड़ी के पूरे जवाब को लॉग करें. इसमें सभी जानकारी शामिल होनी चाहिए. खास तौर पर, अनुरोध आईडी. यह जानकारी डीबग करने के लिए ज़रूरी है. साथ ही, अगर ज़रूरत हो, तो Google की सहायता टीम को समस्याओं की रिपोर्ट करने के लिए भी यह जानकारी ज़रूरी है.

5. उपयोगकर्ताओं से सुझाव/राय/शिकायत पाना: GoogleAdsError कोड और मैसेज के आधार पर, अपने ऐप्लिकेशन के उपयोगकर्ताओं को साफ़ तौर पर और मददगार सुझाव/राय/शिकायत दें. उदाहरण के लिए, सिर्फ़ "एक गड़बड़ी हुई" कहने के बजाय,"कैंपेन का नाम ज़रूरी है" या "विज्ञापन ग्रुप का दिया गया आईडी नहीं मिला" कहा जा सकता है.

इन दिशा-निर्देशों का पालन करके, Google Ads API से मिली गड़बड़ियों का पता लगाया जा सकता है और उन्हें ठीक किया जा सकता है. इससे ज़्यादा स्थिर और इस्तेमाल में आसान ऐप्लिकेशन बनाए जा सकते हैं.