API ত্রুটিগুলি বুঝুন

এই নির্দেশিকাটি ব্যাখ্যা করে যে Google Ads API কীভাবে ত্রুটিগুলি পরিচালনা করে এবং যোগাযোগ করে। API ত্রুটির গঠন এবং অর্থ বোঝা শক্তিশালী অ্যাপ্লিকেশন তৈরির জন্য অত্যন্ত গুরুত্বপূর্ণ যা অবৈধ ইনপুট থেকে শুরু করে অস্থায়ী পরিষেবা অনুপলব্ধতা পর্যন্ত সমস্যাগুলি সুন্দরভাবে পরিচালনা করতে পারে।

Google Ads API স্ট্যান্ডার্ড Google API ত্রুটি মডেল অনুসরণ করে, যা gRPC স্ট্যাটাস কোডের উপর ভিত্তি করে তৈরি। প্রতিটি API প্রতিক্রিয়া যা ত্রুটির কারণ হয় তাতে একটি Status অবজেক্ট থাকে যার মধ্যে রয়েছে:

• একটি সংখ্যাসূচক ত্রুটি কোড।
• একটি ত্রুটি বার্তা।
• ঐচ্ছিক, অতিরিক্ত ত্রুটির বিবরণ।

ক্যানোনিকাল ত্রুটি কোডগুলি

Google Ads API gRPC এবং HTTP দ্বারা সংজ্ঞায়িত কিছু ক্যানোনিকাল ত্রুটি কোড ব্যবহার করে। এই কোডগুলি ত্রুটির ধরণের একটি উচ্চ-স্তরের ইঙ্গিত প্রদান করে। সমস্যার মৌলিক প্রকৃতি বুঝতে আপনার সর্বদা প্রথমে এই সংখ্যাসূচক কোডটি পরীক্ষা করা উচিত।

Google Ads API ব্যবহার করার সময় আপনি যে সাধারণ কোডগুলির মুখোমুখি হতে পারেন তার সংক্ষিপ্তসার নিম্নোক্ত সারণীতে দেওয়া হল:

জিআরপিসি কোড	HTTP কোড	এনাম নাম	বিবরণ	নির্দেশনা
0	২০০	OK	কোনও ত্রুটি নেই; সাফল্যের ইঙ্গিত দেয়।	নিষিদ্ধ
১	৪৯৯	CANCELLED	অপারেশনটি বাতিল করা হয়েছিল, সাধারণত ক্লায়েন্ট দ্বারা।	সাধারণত এর অর্থ হল ক্লায়েন্ট অপেক্ষা করা বন্ধ করে দিয়েছে। ক্লায়েন্ট-সাইড টাইমআউট পরীক্ষা করুন।
২	৫০০	UNKNOWN	একটি অজানা ত্রুটি ঘটেছে। ত্রুটি বার্তা বা বিশদে আরও বিশদ বিবরণ থাকতে পারে।	সার্ভার ত্রুটি হিসেবে বিবেচনা করুন। প্রায়শই ব্যাকঅফ দিয়ে পুনরায় চেষ্টা করা যেতে পারে।
৩	৪০০	INVALID_ARGUMENT	ক্লায়েন্ট একটি অবৈধ আর্গুমেন্ট নির্দিষ্ট করেছে। এটি এমন একটি সমস্যা নির্দেশ করে যা API কে অনুরোধ প্রক্রিয়াকরণ থেকে বিরত রাখে, যেমন একটি ত্রুটিপূর্ণ রিসোর্স নাম বা অবৈধ মান।	ক্লায়েন্ট ত্রুটি: আপনার অনুরোধের প্যারামিটারগুলি পর্যালোচনা করুন এবং নিশ্চিত করুন যে সেগুলি API প্রয়োজনীয়তা পূরণ করে। ত্রুটির বিবরণ সাধারণত কোন যুক্তিটি অবৈধ ছিল এবং কীভাবে - অনুরোধটি ঠিক করতে এই বিবরণগুলি ব্যবহার করুন সে সম্পর্কে তথ্য প্রদান করে। অনুরোধটি ঠিক না করে আবার চেষ্টা করবেন না।
৪	৫০৪	DEADLINE_EXCEEDED	অপারেশন শেষ হওয়ার আগেই সময়সীমা শেষ হয়ে গেল।	সার্ভার ত্রুটি: প্রায়শই ক্ষণস্থায়ী। সূচকীয় ব্যাকঅফ দিয়ে পুনরায় চেষ্টা করার কথা বিবেচনা করুন।
৫	৪০৪	NOT_FOUND	কিছু অনুরোধকৃত সত্তা, যেমন একটি প্রচারণা বা বিজ্ঞাপন গোষ্ঠী, খুঁজে পাওয়া যায়নি।	ক্লায়েন্ট ত্রুটি: আপনি যে রিসোর্সগুলি অ্যাক্সেস করার চেষ্টা করছেন তার অস্তিত্ব এবং আইডি যাচাই করুন। সংশোধন না করে পুনরায় চেষ্টা করবেন না।
৬	৪০৯	ALREADY_EXISTS	ক্লায়েন্ট যে সত্তা তৈরি করার চেষ্টা করেছিলেন তা ইতিমধ্যেই বিদ্যমান।	ক্লায়েন্ট ত্রুটি: ডুপ্লিকেট রিসোর্স তৈরি করা এড়িয়ে চলুন। রিসোর্সটি তৈরি করার চেষ্টা করার আগে এটি বিদ্যমান কিনা তা পরীক্ষা করে নিন।
৭	৪০৩	PERMISSION_DENIED	কলকারীর নির্দিষ্ট ক্রিয়াকলাপটি সম্পাদন করার অনুমতি নেই।	ক্লায়েন্ট ত্রুটি: Google বিজ্ঞাপন অ্যাকাউন্টের জন্য প্রমাণীকরণ , অনুমোদন এবং ব্যবহারকারীর ভূমিকা পরীক্ষা করুন। অনুমতিগুলি সমাধান না করে আবার চেষ্টা করবেন না।
৮	৪২৯	RESOURCE_EXHAUSTED	হয় একটি রিসোর্স শেষ হয়ে গেছে (উদাহরণস্বরূপ, আপনি আপনার কোটা অতিক্রম করেছেন), অথবা একটি সিস্টেম ওভারলোড হয়ে গেছে।	ক্লায়েন্ট/সার্ভার ত্রুটি: সাধারণত অপেক্ষা করতে হয়। সূচকীয় ব্যাকঅফ বাস্তবায়ন করুন এবং সম্ভাব্যভাবে অনুরোধের হার কমিয়ে দিন। API সীমা এবং কোটা দেখুন।
৯	৪০০	FAILED_PRECONDITION	অপারেশনটি বাতিল করা হয়েছে কারণ সিস্টেমটি অপারেশনটি সম্পাদনের জন্য প্রয়োজনীয় অবস্থায় নেই। উদাহরণস্বরূপ, একটি প্রয়োজনীয় ক্ষেত্র অনুপস্থিত।	ক্লায়েন্ট ত্রুটি: অনুরোধটি বৈধ, কিন্তু অবস্থা ভুল। পূর্বশর্ত ব্যর্থতা বুঝতে ত্রুটির বিবরণ পর্যালোচনা করুন। অবস্থা সংশোধন না করে পুনরায় চেষ্টা করবেন না।
১০	৪০৯	ABORTED	সাধারণত লেনদেনের দ্বন্দ্বের মতো একটি কনকারেন্সি সমস্যার কারণে অপারেশনটি বাতিল করা হয়েছিল।	সার্ভার ত্রুটি: প্রায়শই একটি সংক্ষিপ্ত ব্যাকঅফ দিয়ে পুনরায় চেষ্টা করা নিরাপদ।
১১	৪০০	OUT_OF_RANGE	অপারেশনটি বৈধ পরিসরের বাইরে যাওয়ার চেষ্টা করা হয়েছিল।	ক্লায়েন্ট ত্রুটি: পরিসর বা সূচী সংশোধন করুন।
১২	৫০১	UNIMPLEMENTED	অপারেশনটি বাস্তবায়িত হয়নি অথবা API দ্বারা সমর্থিত নয়।	ক্লায়েন্ট ত্রুটি: API সংস্করণ এবং উপলব্ধ বৈশিষ্ট্যগুলি পরীক্ষা করুন। পুনরায় চেষ্টা করবেন না।
১৩	৫০০	INTERNAL	একটি অভ্যন্তরীণ ত্রুটি ঘটেছে। এটি সার্ভার-সাইড সমস্যার জন্য একটি সাধারণ সমাধান।	সার্ভার ত্রুটি: সাধারণত এক্সপোনেনশিয়াল ব্যাকঅফ সহ পুনরায় চেষ্টা করা যায়। যদি সমস্যাটি অব্যাহত থাকে, তাহলে সমস্যাটি রিপোর্ট করুন ।
১৪	৫০৩	UNAVAILABLE	পরিষেবাটি বর্তমানে অনুপলব্ধ। এটি সম্ভবত একটি ক্ষণস্থায়ী অবস্থা।	সার্ভার ত্রুটি: এক্সপোনেনশিয়াল ব্যাকঅফ দিয়ে পুনরায় চেষ্টা করার জন্য অত্যন্ত সুপারিশ করা হচ্ছে।
১৫	৫০০	DATA_LOSS	অপ্রত্যাশিত তথ্য ক্ষতি বা দুর্নীতি।	সার্ভার ত্রুটি: বিরল। এটি একটি গুরুতর সমস্যা নির্দেশ করে। পুনরায় চেষ্টা করবেন না। যদি বারবার সমস্যাটি দেখা দেয়, তাহলে সমস্যাটি রিপোর্ট করুন ।
১৬	৪০১	UNAUTHENTICATED	অনুরোধটির বৈধ প্রমাণীকরণ শংসাপত্র নেই।	ক্লায়েন্ট ত্রুটি: আপনার প্রমাণীকরণ টোকেন এবং শংসাপত্র যাচাই করুন। প্রমাণীকরণ ঠিক না করে আবার চেষ্টা করবেন না।

এই কোডগুলি সম্পর্কে আরও তথ্যের জন্য, API ডিজাইন গাইড - ত্রুটি কোডগুলি দেখুন।

ত্রুটির বিবরণ বুঝুন

টপ-লেভেল কোডের বাইরে, 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.v17.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 )।

ত্রুটির বিবরণ খুঁজুন

আপনি কীভাবে ত্রুটির বিবরণ অ্যাক্সেস করবেন তা নির্ভর করে আপনি স্ট্যান্ডার্ড API কল ব্যবহার করছেন, আংশিক ব্যর্থতা, নাকি স্ট্রিমিং করছেন তার উপর।

স্ট্যান্ডার্ড এবং স্ট্রিমিং API কল

যখন কোনও API কল আংশিক ব্যর্থতা ব্যবহার না করে ব্যর্থ হয়, যার মধ্যে স্ট্রিমিং কলও অন্তর্ভুক্ত, তখন GoogleAdsFailure অবজেক্টটি gRPC রেসপন্স হেডারে ট্রেলিং মেটাডেটার অংশ হিসাবে ফেরত পাঠানো হয়। আপনি যদি স্ট্যান্ডার্ড কলের জন্য REST ব্যবহার করেন, তাহলে HTTP রেসপন্সে GoogleAdsFailure ফেরত পাঠানো হয়। ক্লায়েন্ট লাইব্রেরিগুলি সাধারণত GoogleAdsFailure অ্যাট্রিবিউটের সাথে এটিকে ব্যতিক্রম হিসাবে প্রকাশ করে।

আংশিক ব্যর্থতা

যদি আপনি partial failure ব্যবহার করেন, তাহলে ব্যর্থ ক্রিয়াকলাপের ত্রুটিগুলি প্রতিক্রিয়ার partial_failure_error ক্ষেত্রে ফেরত পাঠানো হবে, প্রতিক্রিয়া শিরোনামে নয়। এই ক্ষেত্রে, GoogleAdsFailure প্রতিক্রিয়ার একটি google.rpc.Status অবজেক্টের মধ্যে এমবেড করা আছে।

ব্যাচ জবস

ব্যাচ প্রক্রিয়াকরণের জন্য, কাজ শেষ হওয়ার পরে ব্যাচ কাজের ফলাফল পুনরুদ্ধার করে পৃথক ক্রিয়াকলাপের ত্রুটিগুলি খুঁজে পাওয়া যেতে পারে। প্রতিটি অপারেশনের ফলাফলে একটি status ফিল্ড থাকবে যেখানে অপারেশন ব্যর্থ হলে ত্রুটির বিবরণ থাকবে।

অনুরোধ আইডি

request-id হল একটি অনন্য স্ট্রিং যা আপনার API অনুরোধ শনাক্ত করে এবং সমস্যা সমাধানের জন্য এটি অপরিহার্য।

আপনি একাধিক জায়গায় request-id খুঁজে পেতে পারেন:

• GoogleAdsFailure : যদি একটি API কল ব্যর্থ হয় এবং GoogleAdsFailure ফেরত পাঠানো হয়, তাহলে এতে একটি request_id থাকবে।
• ট্রেইলিং মেটাডেটা : সফল এবং ব্যর্থ উভয় অনুরোধের জন্য, gRPC প্রতিক্রিয়ার ট্রেইলিং মেটাডেটায় request-id পাওয়া যায়।
• রেসপন্স হেডার : সফল এবং ব্যর্থ উভয় অনুরোধের জন্য, request-id gRPC এবং HTTP রেসপন্স হেডারেও পাওয়া যায়, সফল স্ট্রিমিং অনুরোধগুলি বাদে।
• SearchGoogleAdsStreamResponse : স্ট্রিমিং অনুরোধের জন্য, প্রতিটি SearchGoogleAdsStreamResponse বার্তায় একটি request_id ক্ষেত্র থাকে।

ত্রুটি লগ করার সময় বা সহায়তার সাথে যোগাযোগ করার সময়, সমস্যা নির্ণয়ে সহায়তা করার জন্য request-id অন্তর্ভুক্ত করতে ভুলবেন না।

ত্রুটি পরিচালনার জন্য সেরা অনুশীলন

স্থিতিস্থাপক অ্যাপ্লিকেশন তৈরি করতে, নিম্নলিখিত সেরা অনুশীলনগুলি বাস্তবায়ন করুন:

1. ত্রুটির বিবরণ পরীক্ষা করুন: সর্বদা Status অবজেক্টের details ক্ষেত্রটি বিশ্লেষণ করুন, বিশেষ করে GoogleAdsFailure খুঁজুন। GoogleAdsError মধ্যে থাকা errorCode , message এবং location ডিবাগিং এবং ব্যবহারকারীর প্রতিক্রিয়ার জন্য সবচেয়ে কার্যকর তথ্য প্রদান করে।

2. ক্লায়েন্ট এবং সার্ভার ত্রুটির মধ্যে পার্থক্য করুন:

   • ক্লায়েন্ট ত্রুটি: INVALID_ARGUMENT , NOT_FOUND , PERMISSION_DENIED , FAILED_PRECONDITION , UNAUTHENTICATED এর মতো কোড। এর জন্য অনুরোধে অথবা আপনার অ্যাপ্লিকেশনের অবস্থা/প্রমাণপত্রে পরিবর্তন প্রয়োজন। সমস্যাটির সমাধান না করে অনুরোধটি পুনরায় চেষ্টা করবেন না।
   • সার্ভার ত্রুটি: UNAVAILABLE , INTERNAL , DEADLINE_EXCEEDED , UNKNOWN মতো কোড। এগুলো API পরিষেবার সাথে একটি অস্থায়ী সমস্যার ইঙ্গিত দেয়।

3. পুনরায় চেষ্টা করার কৌশল বাস্তবায়ন করুন:

   • কখন পুনরায় চেষ্টা করবেন: শুধুমাত্র UNAVAILABLE , DEADLINE_EXCEEDED , INTERNAL , UNKNOWN , এবং ABORTED এর মতো ক্ষণস্থায়ী সার্ভার ত্রুটির জন্য পুনরায় চেষ্টা করুন।
   • সূচকীয় ব্যাকঅফ: পুনরায় চেষ্টার মধ্যে ক্রমবর্ধমান সময়কালের জন্য অপেক্ষা করার জন্য একটি সূচকীয় ব্যাকঅফ অ্যালগরিদম ব্যবহার করুন। এটি ইতিমধ্যেই চাপযুক্ত পরিষেবাকে অতিরিক্ত চাপ এড়াতে সাহায্য করে। উদাহরণস্বরূপ, 1 সেকেন্ড, তারপর 2 সেকেন্ড, তারপর 4 সেকেন্ড অপেক্ষা করুন, সর্বোচ্চ সংখ্যক পুনরায় চেষ্টা বা মোট অপেক্ষার সময় পর্যন্ত।
   • জিটার: "বজ্রপাতের দল" সমস্যা প্রতিরোধ করার জন্য ব্যাকঅফ বিলম্বে অল্প পরিমাণে "জিটার" যোগ করুন যেখানে অনেক ক্লায়েন্ট একসাথে পুনরায় চেষ্টা করে।

4. পুঙ্খানুপুঙ্খভাবে লগ করুন: সমস্ত বিবরণ সহ সম্পূর্ণ ত্রুটি প্রতিক্রিয়া লগ করুন, বিশেষ করে অনুরোধ আইডি। ডিবাগিংয়ের জন্য এবং প্রয়োজনে গুগল সহায়তায় সমস্যাগুলি রিপোর্ট করার জন্য এই তথ্যটি অপরিহার্য।

5. ব্যবহারকারীর প্রতিক্রিয়া প্রদান করুন: নির্দিষ্ট GoogleAdsError কোড এবং বার্তাগুলির উপর ভিত্তি করে, আপনার অ্যাপ্লিকেশনের ব্যবহারকারীদের স্পষ্ট এবং সহায়ক প্রতিক্রিয়া প্রদান করুন। উদাহরণস্বরূপ, কেবল "একটি ত্রুটি ঘটেছে" এর পরিবর্তে, আপনি "প্রচারণার নাম প্রয়োজন" বা "প্রদত্ত বিজ্ঞাপন গ্রুপ আইডি পাওয়া যায়নি" বলতে পারেন।

এই নির্দেশিকাগুলি অনুসরণ করে, আপনি Google Ads API দ্বারা ফেরত আসা ত্রুটিগুলি কার্যকরভাবে নির্ণয় এবং পরিচালনা করতে পারবেন, যার ফলে আরও স্থিতিশীল এবং ব্যবহারকারী-বান্ধব অ্যাপ্লিকেশন তৈরি হবে।