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

इस गाइड में, 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 ऑब्जेक्ट में ये चीज़ें शामिल होती हैं:

  • 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.v24.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, क्रमशः).

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

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

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

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

आंशिक गड़बड़ी

अगर आंशिक गड़बड़ी का इस्तेमाल किया जा रहा है, तो पूरी न हो पाने वाली कार्रवाइयों से जुड़ी गड़बड़ियां, रिस्पॉन्स हेडर में नहीं, बल्कि रिस्पॉन्स के 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 देखें. ज़्यादा जानकारी वाले errorCode, message, और location से, डीबग करने और उपयोगकर्ता के सुझाव/शिकायत या राय के लिए सबसे ज़्यादा काम की जानकारी मिलती है.GoogleAdsError

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

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