ত্রুটিগুলি সমাধান করুন

জিমেইল এপিআই দুই স্তরের ত্রুটির তথ্য প্রদান করে:

  • হেডারে থাকা HTTP ত্রুটি কোড এবং বার্তা।
  • রেসপন্স বডিতে একটি JSON অবজেক্ট থাকে, যাতে অতিরিক্ত বিবরণ থাকে যা আপনাকে ত্রুটিটি কীভাবে সমাধান করতে হবে তা নির্ধারণ করতে সাহায্য করতে পারে।

REST API ব্যবহার করার সময় আপনার Gmail অ্যাপের উচিত সমস্ত ত্রুটি শনাক্ত করা এবং সেগুলোর সমাধান করা। এই নির্দেশিকায় নির্দিষ্ট Gmail API ত্রুটিগুলি কীভাবে সমাধান করা যায়, সে সম্পর্কে নির্দেশনা দেওয়া হয়েছে।

HTTP স্ট্যাটাস কোডের সারাংশ

ত্রুটি কোড বর্ণনা
200 - OK অনুরোধটি সফল হয়েছে (সফল HTTP অনুরোধের জন্য এটিই সাধারণ প্রতিক্রিয়া)।
400 - Bad Request ক্লায়েন্টের ত্রুটির কারণে সার্ভার অনুরোধটি পূরণ করতে পারেনি।
401 - Unauthorized অনুরোধটিতে অবৈধ পরিচয়পত্র রয়েছে।
403 - Forbidden সার্ভার অনুরোধটি গ্রহণ ও বুঝতে পেরেছে, কিন্তু অনুরোধটি সম্পাদন করার অনুমতি ব্যবহারকারীর নেই।
404 - Not Found অনুরোধকৃত রিসোর্সটি খুঁজে পাওয়া যায়নি।
429 - Too Many Requests এপিআই-তে অতিরিক্ত অনুরোধ পাঠানো হয়েছে।
500, 502, 503, 504 - Server Errors অনুরোধটি প্রক্রিয়াকরণ করার সময় একটি অপ্রত্যাশিত ত্রুটি ঘটেছে।

৪০০টি ত্রুটি

এই ত্রুটিগুলোর অর্থ হলো অনুরোধটিতে একটি ভুল রয়েছে, যা প্রায়শই কোনো প্রয়োজনীয় প্যারামিটার অনুপস্থিত থাকার কারণে ঘটে থাকে।

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 ফিল্ডটি পরীক্ষা করুন এবং সেই অনুযায়ী আপনার কোড সংশোধন করুন।

৪০১টি ত্রুটি

এই ত্রুটিগুলোর অর্থ হলো অনুরোধটিতে কোনো বৈধ অ্যাক্সেস টোকেন নেই।

authError

আপনার ব্যবহৃত অ্যাক্সেস টোকেনটি মেয়াদোত্তীর্ণ বা অবৈধ হলে এই ত্রুটিটি ঘটে। অনুরোধ করা স্কোপগুলির জন্য অনুমোদন না থাকলেও এই ত্রুটি হতে পারে। নিম্নলিখিত JSON নমুনাটি এই ত্রুটির একটি প্রতিরূপ:

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

এই ত্রুটিটি সমাধান করতে, দীর্ঘস্থায়ী রিফ্রেশ টোকেন ব্যবহার করে অ্যাক্সেস টোকেনটি রিফ্রেশ করুন। আপনি যদি কোনো ক্লায়েন্ট লাইব্রেরি ব্যবহার করেন, তবে এটি স্বয়ংক্রিয়ভাবে টোকেন রিফ্রেশের কাজটি করে। যদি এটি ব্যর্থ হয়, তবে ‘অথেনটিকেশন এবং অথরাইজেশন সম্পর্কে জানুন’ অংশে বর্ণিত পদ্ধতি অনুযায়ী ব্যবহারকারীকে OAuth ফ্লো-এর মাধ্যমে পরিচালিত করুন।

জিমেইলের সীমাবদ্ধতা সম্পর্কে অতিরিক্ত তথ্যের জন্য, ব্যবহারের সীমাবদ্ধতা দেখুন।

৪০৩টি ত্রুটি

ব্যবহারের সীমা অতিক্রম করলে বা ব্যবহারকারীর সঠিক অধিকার না থাকলে এই ত্রুটিগুলো ঘটে। কারণ নির্ধারণ করতে, ফেরত আসা JSON-এর reason ফিল্ডটি মূল্যায়ন করুন। নিম্নলিখিত পরিস্থিতিতে এই ত্রুটিটি ঘটে:

  • আপনার অ্যাপটি প্রমাণীকৃত ব্যবহারকারীর ডোমেইনের মধ্যে ব্যবহার করা যাবে না।
  • প্রকল্পটি দৈনিক সীমা অতিক্রম করেছে।
  • ব্যবহারকারী রেট লিমিট অতিক্রম করেছেন।
  • প্রকল্পটি নির্ধারিত হারের সীমা অতিক্রম করেছে।

আরও তথ্যের জন্য, ব্যবহারের সীমা দেখুন।

dailyLimitExceeded

আপনার প্রজেক্ট তার API সীমায় পৌঁছালে এই ত্রুটিটি ঘটে। নিম্নলিখিত JSON নমুনাটি এই ত্রুটির একটি প্রতিরূপ:

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

এই ত্রুটিটি ঘটে যখন অ্যাপ্লিকেশন মালিক কোনো নির্দিষ্ট রিসোর্সের ব্যবহার সীমিত করার জন্য একটি কোটা সীমা নির্ধারণ করেন। এই ত্রুটিটি সমাধান করতে, Google Cloud প্রজেক্টে কোটা বাড়িয়ে দিন। আরও তথ্যের জন্য, ‘কোটা সীমা পরিচালনা’ দেখুন।

domainPolicy

এই ত্রুটিটি ঘটে যখন ব্যবহারকারীর ডোমেনের নীতি আপনার অ্যাপকে জিমেইল অ্যাক্সেস করার অনুমতি দেয় না। নিম্নলিখিত 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."
  }
}

এই ত্রুটিটি সমাধান করতে, নিম্নলিখিতগুলি চেষ্টা করুন:

  1. ব্যবহারকারীকে জানান যে ডোমেইনটি আপনার অ্যাপকে জিমেইল অ্যাক্সেস করার অনুমতি দেয় না।
  2. আপনার অ্যাপের অ্যাক্সেসের জন্য অনুরোধ করতে ব্যবহারকারীকে তার ডোমেইন অ্যাডমিনিস্ট্রেটরের সাথে যোগাযোগ করতে নির্দেশ দিন।

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 "Too many requests" ত্রুটি দেখা দিতে পারে। প্রতিটি সীমা সম্পর্কে তথ্য নিচে দেওয়া হলো। তবে, ব্যর্থ অনুরোধগুলো পুনরায় চেষ্টা করে অথবা একাধিক Gmail অ্যাকাউন্টের মধ্যে প্রসেসিং ভাগ করে প্রতিটি সীমার সমাধান করা যেতে পারে।

আপনি ব্যবহারকারী-ভিত্তিক সীমা বাড়াতে পারবেন না। সীমা সম্পর্কে আরও তথ্যের জন্য, ব্যবহারের সীমা দেখুন।

মেইল পাঠানোর সীমা

জিমেইল এপিআই দৈনিক মেইল ​​পাঠানোর সাধারণ সীমা প্রয়োগ করে। এই সীমাগুলো অর্থপ্রদানকারী গুগল ওয়ার্কস্পেস ব্যবহারকারী এবং জিমেইল.কম-এর ট্রায়াল ব্যবহারকারীদের জন্য ভিন্ন। এই সীমাগুলো সম্পর্কে জানতে, গুগল ওয়ার্কস্পেস-এ জিমেইল পাঠানোর সীমা দেখুন।

এই সীমাগুলো ব্যবহারকারী-ভিত্তিক এবং ব্যবহারকারীর সমস্ত ক্লায়েন্টের জন্য প্রযোজ্য, তা এপিআই ক্লায়েন্ট, বিল্ট-ইন বা ওয়েব ক্লায়েন্ট, অথবা এসএমটিপি এমএসএ যাই হোক না কেন। আপনি যদি এই সীমাগুলো অতিক্রম করেন, তাহলে এপিআই একটি পুনঃপ্রচেষ্টার সময়সহ HTTP 429 "Too many requests: User-rate limit exceeded (Mail sending)" ত্রুটি ফেরত দেয়। দৈনিক সীমা অতিক্রম করলে, সার্ভার অনুরোধটি গ্রহণ করার আগে বেশ কয়েক ঘন্টা ধরে এই ত্রুটিগুলো দেখা দিতে পারে।

ইমেল পাঠানোর প্রক্রিয়াটি জটিল: ব্যবহারকারী তার কোটা অতিক্রম করলে, এপিআই (API) ৪২৯ এরর রেসপন্স (error response) পাঠানো শুরু করার আগে কয়েক মিনিটের বিলম্ব হতে পারে। ২০০ রেসপন্স পেলেই যে ইমেলটি সফলভাবে পাঠানো হয়েছে, তা ধরে নেওয়া যায় না।

ব্যান্ডউইথ সীমা

এপিআই-এর ব্যবহারকারী-ভিত্তিক আপলোড এবং ডাউনলোড ব্যান্ডউইথ সীমা রয়েছে, যা IMAP-এর সমান কিন্তু স্বাধীন। এই সীমাগুলো একজন ব্যবহারকারীর জন্য সমস্ত জিমেইল এপিআই ক্লায়েন্ট জুড়ে একই থাকে।

ব্যবহারকারীরা সাধারণত ব্যতিক্রমী বা অপব্যবহারমূলক পরিস্থিতিতেই এই সীমাগুলোর সম্মুখীন হন। আপনি এই সীমাগুলো অতিক্রম করলে, API একটি পুনঃপ্রচেষ্টার সময়সহ HTTP 429 "Too many requests: User-rate limit exceeded" ত্রুটি ফেরত দেয়। দৈনিক সীমা অতিক্রম করলে, সার্ভার অনুরোধটি গ্রহণ করার আগে বেশ কয়েক ঘন্টা ধরে এই ত্রুটিগুলো দেখা দিতে পারে।

একই সাথে একাধিক অনুরোধ

জিমেইল এপিআই ব্যবহারকারী-ভিত্তিক রেট লিমিটের পাশাপাশি ব্যবহারকারী-প্রতি একযোগে অনুরোধের একটি সীমাও প্রয়োগ করে। এই সীমাটি একজন ব্যবহারকারীকে অ্যাক্সেসকারী সমস্ত জিমেইল এপিআই ক্লায়েন্টের জন্য প্রযোজ্য এবং এটি নিশ্চিত করে যে কোনো এপিআই ক্লায়েন্ট যেন কোনো জিমেইল ব্যবহারকারীর মেইলবক্স বা তাদের ব্যাকএন্ড সার্ভারকে অতিরিক্ত ভারাক্রান্ত না করে।

একজন ব্যবহারকারীর জন্য একই সাথে অনেকগুলো অনুরোধ করলে অথবা একসাথে অনেক অনুরোধ পাঠালে এই ত্রুটি দেখা দিতে পারে। একই সময়ে অনেকগুলো স্বতন্ত্র এপিআই ক্লায়েন্ট জিমেইল ব্যবহারকারীর মেইলবক্স অ্যাক্সেস করলেও এই ত্রুটি দেখা দিতে পারে। আপনি এই সীমা অতিক্রম করলে, এপিআই একটি HTTP 429 "Too many requests: Too many concurrent requests for user" ত্রুটি ফেরত দেয়।

৫০০, ৫০২, ৫০৩, ৫০৪ ত্রুটি

অনুরোধটি প্রক্রিয়া করার সময় কোনো অপ্রত্যাশিত সার্ভার ত্রুটি দেখা দিলে এই ত্রুটিগুলো ঘটে। বিভিন্ন কারণে এই ত্রুটিগুলো হতে পারে, যার মধ্যে রয়েছে একটি অনুরোধের সময় অন্য কোনো অনুরোধের সময়ের সাথে মিলে যাওয়া অথবা কোনো অসমর্থিত কাজের জন্য অনুরোধ করা; যেমন, পুরো সাইটের পরিবর্তে গুগল সাইটসের (Google Sites) একটিমাত্র পৃষ্ঠার অনুমতি হালনাগাদ করার চেষ্টা করা।

নিচে 5xx ত্রুটিগুলোর একটি তালিকা দেওয়া হলো:

  • ৫০০ ব্যাকএন্ড ত্রুটি
  • ৫০২ ত্রুটিপূর্ণ গেটওয়ে
  • ৫০৩ পরিষেবা অনুপলব্ধ
  • ৫০৪ গেটওয়ে টাইমআউট

backendError

অনুরোধটি প্রক্রিয়াকরণের সময় কোনো অপ্রত্যাশিত ত্রুটি দেখা দিলে এই ত্রুটিটি ঘটে। নিম্নলিখিত JSON নমুনাটি এই ত্রুটির একটি প্রতিরূপ:

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

এই ত্রুটিটি সমাধান করতে, অনুরোধটি পুনরায় চেষ্টা করার জন্য এক্সপোনেনশিয়াল ব্যাকঅফ ব্যবহার করুন।

ত্রুটি সমাধানের জন্য ব্যর্থ অনুরোধগুলি পুনরায় চেষ্টা করুন।

রেট লিমিট, নেটওয়ার্ক ভলিউম বা রেসপন্স টাইম সম্পর্কিত ত্রুটিগুলো সামাল দিতে আপনি একটি ব্যর্থ অনুরোধকে ক্রমবর্ধমান সময় ধরে পর্যায়ক্রমে পুনরায় চেষ্টা করতে পারেন। উদাহরণস্বরূপ, আপনি একটি ব্যর্থ অনুরোধ এক সেকেন্ড পর, তারপর দুই সেকেন্ড পর এবং তারপর চার সেকেন্ড পর পুনরায় চেষ্টা করতে পারেন। এই পদ্ধতিকে এক্সপোনেনশিয়াল ব্যাকঅফ বলা হয় এবং এটি কনকারেন্ট পরিবেশে ব্যান্ডউইথের ব্যবহার উন্নত করতে ও অনুরোধের থ্রুপুট সর্বাধিক করতে ব্যবহৃত হয়।

ত্রুটির অন্তত এক সেকেন্ড পর পুনরায় চেষ্টা শুরু করুন।

কোটার সীমা পরিচালনা করুন

আপনার প্রোজেক্টের ব্যবহারের সীমা দেখতে বা পরিবর্তন করতে, অথবা আপনার কোটা বাড়ানোর অনুরোধ করতে, নিম্নলিখিতগুলি করুন:

  1. আপনার প্রোজেক্টের জন্য যদি আগে থেকে কোনো বিলিং অ্যাকাউন্ট না থাকে, তাহলে একটি তৈরি করুন।
  2. এপিআই কনসোলে থাকা এপিআই লাইব্রেরির 'এনাবলড এপিআই' পেজটিতে যান এবং তালিকা থেকে একটি এপিআই নির্বাচন করুন।
  3. কোটা-সম্পর্কিত সেটিংস দেখতে ও পরিবর্তন করতে, ‘কোটা’ নির্বাচন করুন। ব্যবহারের পরিসংখ্যান দেখতে, ‘ব্যবহার’ নির্বাচন করুন।

আরও তথ্যের জন্য, ‘কোটা দেখুন ও পরিচালনা করুন’ দেখুন।

ব্যাচ অনুরোধ

ব্যাচ রিকোয়েস্ট পারফরম্যান্স উন্নত করতে পারে, কিন্তু বড় আকারের ব্যাচ রেট লিমিটিং চালু করে দিতে পারে। ৫০টির বেশি রিকোয়েস্টের ব্যাচ পাঠাবেন না। কীভাবে ব্যাচ রিকোয়েস্ট পাঠাতে হয়, সে সম্পর্কে জানতে ‘ব্যাচ রিকোয়েস্ট’ অংশটি দেখুন।