गड़बड़ियां ठीक करना

Gmail API, गड़बड़ी की जानकारी के दो लेवल दिखाता है:

हेडर में एचटीटीपी गड़बड़ी के कोड और मैसेज.
जवाब के मुख्य हिस्से में मौजूद JSON ऑब्जेक्ट में, गड़बड़ी के बारे में ज़्यादा जानकारी होती है. इससे आपको यह तय करने में मदद मिलती है कि गड़बड़ी को कैसे ठीक किया जाए.

Gmail ऐप्लिकेशन को, REST API का इस्तेमाल करते समय होने वाली सभी गड़बड़ियों का पता लगाना चाहिए और उन्हें ठीक करना चाहिए. इस गाइड में, Gmail API से जुड़ी कुछ गड़बड़ियों को ठीक करने का तरीका बताया गया है.

एचटीटीपी स्टेटस कोड की खास जानकारी

गड़बड़ी का कोड	ब्यौरा
`200 - OK`	अनुरोध पूरा हो गया है. यह एचटीटीपी अनुरोधों के पूरा होने पर मिलने वाला स्टैंडर्ड रिस्पॉन्स है.
`400 - Bad Request`	अनुरोध में क्लाइंट की गड़बड़ी की वजह से, अनुरोध पूरा नहीं किया जा सकता.
`401 - Unauthorized`	अनुरोध में अमान्य क्रेडेंशियल शामिल हैं.
`403 - Forbidden`	अनुरोध मिल गया है और उसे समझ लिया गया है. हालांकि, उपयोगकर्ता के पास अनुरोध पूरा करने की अनुमति नहीं है.
`404 - Not Found`	अनुरोध किया गया पेज नहीं मिला.
`429 - Too Many Requests`	API के लिए बहुत ज़्यादा अनुरोध किए गए हैं.
`500, 502, 503, 504 - Server Errors`	अनुरोध को प्रोसेस करते समय कोई गड़बड़ी हुई.

400 गड़बड़ियां

इन गड़बड़ियों का मतलब है कि अनुरोध में कोई गड़बड़ी है. ऐसा अक्सर किसी ज़रूरी पैरामीटर की वैल्यू मौजूद न होने की वजह से होता है.

`badRequest`

आपके कोड में इनमें से किसी भी समस्या की वजह से यह गड़बड़ी हो सकती है:

कोई ज़रूरी फ़ील्ड या पैरामीटर नहीं दिया गया है.
दी गई वैल्यू या फ़ील्ड का कॉम्बिनेशन अमान्य है.
अटैचमेंट अमान्य है.

इस गड़बड़ी को JSON के इस उदाहरण में दिखाया गया है:

{
  "error": {
    "code": 400,
    "errors": [
      {
        "domain": "global",
        "location": "orderBy",
        "locationType": "parameter",
        "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order.",
        "reason": "badRequest"
      }
    ],
    "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order."
  }
}

इस गड़बड़ी को ठीक करने के लिए, message फ़ील्ड देखें और अपने कोड में ज़रूरी बदलाव करें.

401 गड़बड़ियां

इन गड़बड़ियों का मतलब है कि अनुरोध में मान्य ऐक्सेस टोकन शामिल नहीं है.

`authError`

यह गड़बड़ी तब होती है, जब इस्तेमाल किया जा रहा ऐक्सेस टोकन या तो काम नहीं कर रहा होता है या अमान्य होता है. यह गड़बड़ी, अनुरोध किए गए स्कोप के लिए अनुमति न होने की वजह से भी हो सकती है. इस गड़बड़ी को JSON के इस उदाहरण में दिखाया गया है:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "authError",
        "message": "Invalid Credentials",
        "locationType": "header",
        "location": "Authorization",
      }
    ],
    "code": 401,
    "message": "Invalid Credentials"
  }
}

इस गड़बड़ी को ठीक करने के लिए, लंबे समय तक इस्तेमाल किए जा सकने वाले रीफ़्रेश टोकन का इस्तेमाल करके, ऐक्सेस टोकन को रीफ़्रेश करें. क्लाइंट लाइब्रेरी का इस्तेमाल करने पर, टोकन अपने-आप रीफ़्रेश हो जाता है. अगर ऐसा नहीं होता है, तो उपयोगकर्ता को OAuth फ़्लो के बारे में बताएं. इसके बारे में पहचान की पुष्टि करने और अनुमति देने के बारे में जानें लेख में बताया गया है.

Gmail की सीमाओं के बारे में ज़्यादा जानकारी के लिए, इस्तेमाल की सीमाएं देखें.

403 गड़बड़ियां

ये गड़बड़ियां तब होती हैं, जब इस्तेमाल करने की सीमा पार हो जाती है या उपयोगकर्ता के पास सही अनुमतियां नहीं होती हैं. समस्या की वजह का पता लगाने के लिए, दिखाए गए JSON के reason फ़ील्ड का आकलन करें. यह गड़बड़ी इन स्थितियों में होती है:

आपके ऐप्लिकेशन का इस्तेमाल, पुष्टि किए गए उपयोगकर्ता के डोमेन में नहीं किया जा सकता.
रोज़ की सीमा पार हो गई है.
उपयोगकर्ता की दर सीमा से ज़्यादा हो गई है.
प्रोजेक्ट के लिए तय की गई अनुरोधों की संख्या की सीमा पार हो गई है.

ज़्यादा जानकारी के लिए, इस्तेमाल की सीमाएं देखें.

`dailyLimitExceeded`

यह गड़बड़ी तब होती है, जब आपके प्रोजेक्ट के लिए एपीआई की सीमा पूरी हो गई हो. इस गड़बड़ी को यहां दिए गए JSON के उदाहरण में दिखाया गया है:

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "dailyLimitExceeded",
        "message": "Daily Limit Exceeded"
      }
    ],
    "code": 403,
    "message": "Daily Limit Exceeded"
  }
}

यह गड़बड़ी तब दिखती है, जब ऐप्लिकेशन के मालिक ने किसी संसाधन के इस्तेमाल पर कोटा सीमा सेट की हो. इस गड़बड़ी को ठीक करने के लिए, Google Cloud प्रोजेक्ट में कोटे को बढ़ाएं. ज़्यादा जानकारी के लिए, कोटा की सीमाएं मैनेज करना लेख पढ़ें.

`domainPolicy`

यह गड़बड़ी तब होती है, जब उपयोगकर्ता के डोमेन के लिए बनी नीति के तहत, आपका ऐप्लिकेशन Gmail को ऐक्सेस नहीं कर पाता. इस गड़बड़ी को इस JSON के ज़रिए दिखाया गया है:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "domainPolicy",
        "message": "The domain administrators have disabled Gmail apps."
      }
    ],
    "code": 403,
    "message": "The domain administrators have disabled Gmail apps."
  }
}

इस गड़बड़ी को ठीक करने के लिए, यह तरीका आज़माएं:

उपयोगकर्ता को बताएं कि डोमेन, आपके ऐप्लिकेशन को Gmail ऐक्सेस करने की अनुमति नहीं देता है.
उपयोगकर्ता को निर्देश दें कि वह आपके ऐप्लिकेशन का ऐक्सेस पाने के लिए, अपने डोमेन एडमिन से संपर्क करे.

`rateLimitExceeded`

इस गड़बड़ी का मतलब है कि उपयोगकर्ता ने Gmail API के लिए अनुरोध करने की तय सीमा पूरी कर ली है. यह सीमा, अनुरोध के टाइप के हिसाब से अलग-अलग होती है. इस गड़बड़ी को यहां दिए गए JSON के उदाहरण में दिखाया गया है:

{
  "error": {
  "errors": [
    {
    "domain": "usageLimits",
    "message": "Rate Limit Exceeded",
    "reason": "rateLimitExceeded",
    }
  ],
  "code": 403,
  "message": "Rate Limit Exceeded"
  }
}

इस गड़बड़ी को ठीक करने के लिए, यह तरीका आज़माएं:

कोटा बढ़ाने का अनुरोध करें.
अनुरोध को फिर से भेजने के लिए, एक्स्पोनेंशियल बैकऑफ़ का इस्तेमाल करें.

`userRateLimitExceeded`

यह गड़बड़ी तब होती है, जब किसी उपयोगकर्ता के लिए तय की गई सीमा पूरी हो जाती है. इस गड़बड़ी को दिखाने वाला JSON का उदाहरण यहां दिया गया है:

{
  "error": {
  "errors": [
    {
    "domain": "usageLimits",
    "reason": "userRateLimitExceeded",
    "message": "User Rate Limit Exceeded"
    }
  ],
  "code": 403,
  "message": "User Rate Limit Exceeded"
  }
}

इस गड़बड़ी को ठीक करने के लिए, अपने ऐप्लिकेशन कोड को ऑप्टिमाइज़ करें, ताकि कम अनुरोध किए जा सकें. इसके अलावा, अनुरोध को फिर से करने के लिए, एक्सपोनेंशियल बैकऑफ़ का इस्तेमाल करें.

429 गड़बड़ियां

हर उपयोगकर्ता के लिए तय की गई रोज़ाना की सीमा (इसमें ईमेल भेजने की सीमाएं भी शामिल हैं), बैंडविड्थ की सीमाएं या हर उपयोगकर्ता के लिए एक साथ किए जाने वाले अनुरोध की सीमा की वजह से, 429 "बहुत ज़्यादा अनुरोध" वाली गड़बड़ी हो सकती है. हर सीमा के बारे में यहां जानकारी दी गई है. हालांकि, हर सीमा को इन तरीकों से हल किया जा सकता है: अनुरोध फिर से भेजकर या कई Gmail खातों में प्रोसेसिंग को बांटकर.

हर उपयोगकर्ता के लिए तय की गई सीमा को किसी भी वजह से बढ़ाया नहीं जा सकता. सीमाओं के बारे में ज़्यादा जानने के लिए, इस्तेमाल की सीमाएं देखें.

ईमेल भेजने की सीमाएं

Gmail API, ईमेल भेजने की रोज़ की स्टैंडर्ड सीमाओं को लागू करता है. ये सीमाएं, Google Workspace के पैसे चुकाकर इस्तेमाल करने वाले उपयोगकर्ताओं और बिना किसी शुल्क के आज़माने वाले gmail.com उपयोगकर्ताओं के लिए अलग-अलग होती हैं. इन सीमाओं के बारे में जानने के लिए, Google Workspace में Gmail से ईमेल भेजने की सीमाएं लेख पढ़ें.

ये सीमाएं हर उपयोगकर्ता के लिए होती हैं. इन्हें उपयोगकर्ता के सभी क्लाइंट शेयर करते हैं. ये क्लाइंट, एपीआई क्लाइंट, बिल्ट-इन या वेब क्लाइंट या SMTP MSA हो सकते हैं. अगर इन सीमाओं को पार किया जाता है, तो HTTP 429 "बहुत ज़्यादा अनुरोध: उपयोगकर्ता के लिए तय की गई सीमा पार हो गई है (ईमेल भेजना)" गड़बड़ी का मैसेज दिखता है. साथ ही, दोबारा कोशिश करने का समय भी बताया जाता है. एक दिन में तय की गई सीमा से ज़्यादा अनुरोध करने पर, अनुरोध स्वीकार होने से पहले कई घंटों तक ये गड़बड़ियां दिख सकती हैं.

ईमेल भेजने की प्रोसेस जटिल होती है: जब कोई उपयोगकर्ता अपने कोटे से ज़्यादा ईमेल भेज देता है, तो एपीआई को 429 गड़बड़ी वाले जवाब भेजने में कई मिनट लग सकते हैं. यह नहीं माना जा सकता कि 200 रिस्पॉन्स का मतलब है कि ईमेल भेज दिया गया है.

बैंडविड्थ की सीमाएं

इस एपीआई में, हर उपयोगकर्ता के लिए अपलोड और डाउनलोड करने की बैंडविड्थ की सीमाएं होती हैं. ये सीमाएं, IMAP के बराबर होती हैं, लेकिन इससे अलग होती हैं. ये सीमाएं, किसी उपयोगकर्ता के लिए सभी Gmail API क्लाइंट के साथ शेयर की जाती हैं.

आम तौर पर, इन सीमाओं का उल्लंघन सिर्फ़ कुछ खास मामलों में या गलत इस्तेमाल की वजह से होता है. अगर इन सीमाओं का उल्लंघन किया जाता है, तो HTTP 429 "बहुत ज़्यादा अनुरोध: उपयोगकर्ता के लिए तय सीमा पार हो गई है" गड़बड़ी का मैसेज दिखता है. साथ ही, अनुरोध फिर से करने का समय भी बताया जाता है. रोज़ाना की सीमाएं पार होने पर, अनुरोध स्वीकार होने से पहले कई घंटों तक ये गड़बड़ियां दिख सकती हैं.

एक साथ किए गए अनुरोध

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

किसी एक उपयोगकर्ता के लिए एक साथ कई अनुरोध करने या बड़ी संख्या में अनुरोध वाले बैच भेजने पर, यह गड़बड़ी दिख सकती है. अगर कई एपीआई क्लाइंट, Gmail उपयोगकर्ता के मेलबॉक्स को एक साथ ऐक्सेस करते हैं, तो भी यह गड़बड़ी दिख सकती है. अगर इस सीमा को पार कर लिया जाता है, तो HTTP 429 "बहुत ज़्यादा अनुरोध: उपयोगकर्ता के लिए एक साथ बहुत ज़्यादा अनुरोध" गड़बड़ी का मैसेज दिखता है.

500, 502, 503, 504 गड़बड़ियां

ये गड़बड़ियां तब होती हैं, जब अनुरोध को प्रोसेस करते समय कोई अनचाही सर्वर गड़बड़ी होती है. इन गड़बड़ियों की कई वजहें हो सकती हैं. जैसे, किसी अनुरोध का समय किसी दूसरे अनुरोध के समय से मेल खाना या किसी ऐसी कार्रवाई के लिए अनुरोध करना जिसे अनुमति नहीं है. उदाहरण के लिए, पूरी साइट के बजाय Google Sites में किसी एक पेज के लिए अनुमतियां अपडेट करने की कोशिश करना.

5xx गड़बड़ियों की सूची यहां दी गई है:

500 बैकएंड में गड़बड़ी
502 खराब गेटवे
503 कोड वाली गड़बड़ी: सेवा उपलब्ध नहीं है
504 कोड वाली गड़बड़ी: गेटवे का समय खत्म हो गया है

backendError

अनुरोध को प्रोसेस करते समय कोई गड़बड़ी होने पर यह मैसेज दिखता है. इस गड़बड़ी को JSON के इस उदाहरण में दिखाया गया है:

{
  "error": {
  "errors": [
    {
    "domain": "global",
    "reason": "backendError",
    "message": "Backend Error",
    }
  ],
  "code": 500,
  "message": "Backend Error"
  }
}

इस गड़बड़ी को ठीक करने के लिए, अनुरोध को फिर से भेजने के लिए एक्स्पोनेंशियल बैकऑफ़ का इस्तेमाल करें.

गड़बड़ियों को ठीक करने के लिए, पूरे न हो पाने वाले अनुरोधों को फिर से भेजें

रेट लिमिट, नेटवर्क वॉल्यूम या जवाब देने में लगने वाले समय से जुड़ी गड़बड़ियों को ठीक करने के लिए, समय-समय पर अनुरोध को फिर से भेजा जा सकता है. इसके लिए, समयसीमा को बढ़ाया जा सकता है. उदाहरण के लिए, हो सकता है कि आप किसी अनुरोध के पूरा न होने पर, एक सेकंड बाद फिर से कोशिश करें. इसके बाद, दो सेकंड बाद और फिर चार सेकंड बाद कोशिश करें. इस तरीके को एक्सपोनेंशियल बैकऑफ़ कहा जाता है. इसका इस्तेमाल, बैंडविथ के इस्तेमाल को बेहतर बनाने और एक साथ कई अनुरोधों को प्रोसेस करने वाले एनवायरमेंट में थ्रूपुट को ज़्यादा से ज़्यादा करने के लिए किया जाता है.

गड़बड़ी होने के कम से कम एक सेकंड बाद, फिर से कोशिश करने की अवधि शुरू करें.

कोटा की सीमाएं मैनेज करना

अपने प्रोजेक्ट के लिए इस्तेमाल की सीमाएं देखने या उनमें बदलाव करने के लिए, यह तरीका अपनाएं. इसके अलावा, कोटा बढ़ाने का अनुरोध करने के लिए भी यह तरीका अपनाएं:

अगर आपके प्रोजेक्ट के लिए पहले से कोई बिलिंग खाता नहीं है, तो एक खाता बनाएं.
एपीआई कंसोल में, एपीआई लाइब्रेरी के 'चालू किए गए एपीआई' पेज पर जाएं. इसके बाद, सूची में से कोई एपीआई चुनें.
कोटे से जुड़ी सेटिंग देखने और बदलने के लिए, कोटे को चुनें. इस्तेमाल के आंकड़े देखने के लिए, इस्तेमाल को चुनें.

ज़्यादा जानकारी के लिए, कोटा देखना और मैनेज करना लेख पढ़ें.

एक साथ ग्रुप या बैच में भेजे गए अनुरोध

बैच अनुरोधों का इस्तेमाल करने का सुझाव दिया जाता है. हालांकि, बैच का साइज़ बड़ा होने पर, दर सीमा लागू हो सकती है. हमारा सुझाव है कि 50 से ज़्यादा अनुरोधों वाले बैच न भेजें. एक साथ कई अनुरोध भेजने के तरीके के बारे में जानने के लिए, एक साथ कई अनुरोध भेजने का तरीका लेख पढ़ें.