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

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

গুগল অ্যাডস এপিআই স্ট্যান্ডার্ড গুগল এপিআই এরর মডেল অনুসরণ করে, যা জিআরপিসি স্ট্যাটাস কোডের উপর ভিত্তি করে তৈরি। প্রতিটি এপিআই রেসপন্স, যার ফলে কোনো এরর হয়, তাতে একটি Status অবজেক্ট থাকে, যাতে নিম্নলিখিত বিষয়গুলো অন্তর্ভুক্ত থাকে:

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

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

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

গুগল অ্যাডস এপিআই ব্যবহার করার সময় আপনি সাধারণত যে কোডগুলোর সম্মুখীন হতে পারেন, নিচের সারণিতে সেগুলোর একটি সংক্ষিপ্ত বিবরণ দেওয়া হলো:

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

এই কোডগুলো সম্পর্কে আরও বিস্তারিত জানতে, এপিআই ডিজাইন গাইড - এরর কোডসমূহ দেখুন।

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

শীর্ষ-স্তরের কোডের বাইরে, গুগল অ্যাডস এপিআই ' Status অবজেক্টের ' details ফিল্ডের মধ্যে আরও সুনির্দিষ্ট ত্রুটির তথ্য প্রদান করে। এই ফিল্ডটিতে প্রায়শই একটি GoogleAdsFailure প্রোটো থাকে, যার মধ্যে স্বতন্ত্র GoogleAdsError অবজেক্টগুলোর একটি তালিকা অন্তর্ভুক্ত থাকে।

প্রতিটি GoogleAdsFailure অবজেক্টে রয়েছে:

• errors : GoogleAdsError অবজেক্টগুলোর একটি তালিকা, যার প্রতিটিতে সংঘটিত একটি নির্দিষ্ট ত্রুটির বিবরণ রয়েছে।
• request_id : অনুরোধটির একটি অনন্য আইডি, যা ডিবাগিং এবং সহায়তার জন্য উপযোগী।

প্রতিটি GoogleAdsError অবজেক্ট নিম্নলিখিত বিষয়গুলো প্রদান করে:

• errorCode : একটি আরও সুনির্দিষ্ট, গুগল অ্যাডস এপিআই-নির্দিষ্ট ত্রুটি কোড , যেমন AuthenticationError.NOT_ADS_USER ।
• message : নির্দিষ্ট ত্রুটিটির একটি পাঠযোগ্য বিবরণ।
• trigger : যে মানটির কারণে ত্রুটিটি ঘটেছে, যদি প্রযোজ্য হয়।
• location : অনুরোধের কোথায় ত্রুটিটি ঘটেছে তা বর্ণনা করে, যার মধ্যে ফিল্ড পাথও অন্তর্ভুক্ত থাকে।
• details : ত্রুটির অতিরিক্ত বিবরণ, যেমন অপ্রকাশিত ত্রুটির কারণসমূহ।

ত্রুটির বিবরণের উদাহরণ

যখন আপনি কোনো ত্রুটি পাবেন, তখন আপনার ক্লায়েন্ট লাইব্রেরি আপনাকে এই বিবরণগুলো দেখার সুযোগ দেবে। উদাহরণস্বরূপ, একটি INVALID_ARGUMENT (কোড ৩)-এর ক্ষেত্রে 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 )।

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

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

স্ট্যান্ডার্ড এবং স্ট্রিমিং এপিআই কল

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

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

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

ব্যাচ জব

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

অনুরোধ আইডি

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

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

• GoogleAdsFailure : যদি কোনো API কল ব্যর্থ হয় এবং GoogleAdsFailure রিটার্ন করা হয়, তাহলে তাতে একটি request_id থাকবে।
• ট্রেইলিং মেটাডেটা : সফল এবং ব্যর্থ উভয় অনুরোধের ক্ষেত্রেই, gRPC প্রতিক্রিয়ার ট্রেইলিং মেটাডেটাতে request-id পাওয়া যায়।
• রেসপন্স হেডার : সফল স্ট্রিমিং রিকোয়েস্ট ব্যতীত, সফল এবং ব্যর্থ উভয় রিকোয়েস্টের ক্ষেত্রেই gRPC এবং HTTP রেসপন্স হেডারে request-id পাওয়া যায়।
• 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 ।
   • এক্সপোনেনশিয়াল ব্যাকঅফ: পুনরায় চেষ্টার মধ্যবর্তী সময় বাড়ানোর জন্য একটি এক্সপোনেনশিয়াল ব্যাকঅফ অ্যালগরিদম ব্যবহার করুন। এটি আগে থেকেই চাপের মধ্যে থাকা একটি সার্ভিসকে অতিরিক্ত ভারাক্রান্ত হওয়া থেকে বাঁচাতে সাহায্য করে। উদাহরণস্বরূপ, প্রথমে ১ সেকেন্ড, তারপর ২ সেকেন্ড, তারপর ৪ সেকেন্ড অপেক্ষা করুন এবং এভাবে সর্বোচ্চ সংখ্যক পুনরায় চেষ্টা বা মোট অপেক্ষার সময় পর্যন্ত তা চালিয়ে যান।
   • জিটার: ব্যাকঅফ ডিলে-তে অল্প পরিমাণে এলোমেলো 'জিটার' যোগ করুন, যাতে 'থান্ডারিং হার্ড' সমস্যাটি প্রতিরোধ করা যায়, যেখানে অনেক ক্লায়েন্ট একই সাথে পুনরায় চেষ্টা করে।

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

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

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