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

इस गाइड में बताया गया है कि 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 कार्रवाई को अस्वीकार कर दिया गया, क्योंकि सिस्टम उस स्थिति में नहीं है जो कार्रवाई को पूरा करने के लिए ज़रूरी है. उदाहरण के लिए, कोई ज़रूरी फ़ील्ड मौजूद न होना. क्लाइंट से जुड़ी गड़बड़ी: अनुरोध मान्य है, लेकिन स्टेट गलत है. पहले से तय शर्तें पूरी न होने की वजह जानने के लिए, गड़बड़ी की जानकारी देखें. स्टेटस को सही किए बिना, फिर से कोशिश न करें.
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.v26.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 शामिल होगा.
  • ट्रेलिंग मेटाडेटा: सफल और असफल, दोनों तरह के अनुरोधों के लिए, gRPC रिस्पॉन्स के ट्रेलिंग मेटाडेटा में request-id उपलब्ध होता है.
  • रिस्पॉन्स हेडर: सफल और असफल, दोनों तरह के अनुरोधों के लिए, 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 से मिलने वाली गड़बड़ियों का असरदार तरीके से विश्लेषण किया जा सकता है और उन्हें मैनेज किया जा सकता है. इससे ज़्यादा भरोसेमंद और उपयोगकर्ता के लिए आसान ऐप्लिकेशन बनाए जा सकते हैं.

पीछे जाएं
गड़बड़ी के प्रकार
आगे बढ़ें
आम तौर पर होने वाली गड़बड़ियां