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

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

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

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

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

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

यहां दी गई टेबल में, 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 ऑब्जेक्ट से यह जानकारी मिलती है:

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

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

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

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

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

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

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

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

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

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

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

बैच जॉब

बैच प्रोसेसिंग के लिए, जॉब पूरा होने के बाद BatchJobService.ListBatchJobResults को कॉल करके, अलग-अलग कार्रवाइयों से जुड़ी गड़बड़ियों का पता लगाया जा सकता है. अगर कोई कार्रवाई पूरी नहीं होती है, तो हर कार्रवाई के नतीजे में 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 में मौजूद ज़्यादा जानकारी वाले error_code, 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 से मिली गड़बड़ियों का पता लगाया जा सकता है और उन्हें ठीक किया जा सकता है. इससे ज़्यादा स्थिर और इस्तेमाल में आसान ऐप्लिकेशन बनाए जा सकते हैं.