API সংক্রান্ত সমস্যা বোঝা

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

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

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

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

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

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

gRPC কোড	HTTP কোড	Enum-এর নাম	বিবরণ	নির্দেশিকা
0	200	OK	কোনও সমস্যা নেই; সফল হয়েছে।	প্রযোজ্য নয়
1	499	CANCELLED	অপারেশন বাতিল করা হয়েছে, সাধারণত ক্লায়েন্ট এটি করে থাকে।	সাধারণত এর অর্থ হল ক্লায়েন্ট অপেক্ষা করা বন্ধ করে দিয়েছে। ক্লায়েন্ট-সাইড টাইম-আউট চেক করুন।
2	500	UNKNOWN	কোনও অজানা ত্রুটি ঘটেছে। সমস্যার মেসেজ বা বিবরণে আরও তথ্য থাকতে পারে।	সার্ভারের সমস্যা হিসেবে বিবেচনা করুন। ব্যাকঅফ সহ প্রায়শই আবার চেষ্টা করা যেতে পারে।
3	400	INVALID_ARGUMENT	ক্লায়েন্ট ভুল আর্গুমেন্ট উল্লেখ করেছে। এটি এমন একটি সমস্যাকে নির্দেশ করে যা API-কে অনুরোধ প্রসেস করতে বাধা দেয়, যেমন একটি ভুল ফর্ম্যাট করা রিসোর্সের নাম বা ভুল ভ্যালু।	ক্লায়েন্ট সংক্রান্ত সমস্যা: আপনার অনুরোধের প্যারামিটার পর্যালোচনা করুন এবং সেগুলি API-এর প্রয়োজনীয়তা পূরণ করছে কিনা তা নিশ্চিত করুন। সাধারণত, কোন আর্গুমেন্ট ভুল এবং কীভাবে ভুল হয়েছে সেই সম্পর্কে তথ্য সমস্যার বিবরণে দেওয়া থাকে—অনুরোধ ঠিক করতে এই বিবরণ ব্যবহার করুন। অনুরোধে থাকা সমস্যা সমাধান না করে আবার চেষ্টা করবেন না।
4	504	DEADLINE_EXCEEDED	কাজটি সম্পূর্ণ হওয়ার আগেই সময়সীমা শেষ হয়ে গেছে।	সার্ভার সংক্রান্ত সমস্যা: প্রায়শই সাময়িক। এক্সপোনেনশিয়াল ব্যাক-অফ ব্যবহার করে আবার চেষ্টা করার কথা বিবেচনা করুন।
5	404	NOT_FOUND	অনুরোধ করা কিছু এন্টিটি, যেমন ক্যাম্পেন বা বিজ্ঞাপন গ্রুপ, খুঁজে পাওয়া যায়নি।	ক্লায়েন্ট সংক্রান্ত সমস্যা: আপনি যে রিসোর্স অ্যাক্সেস করার চেষ্টা করছেন সেটির অস্তিত্ব ও আইডি যাচাই করুন। সংশোধন না করে আবার চেষ্টা করবেন না।
6	409	ALREADY_EXISTS	ক্লায়েন্ট যে এন্টিটি তৈরি করার চেষ্টা করেছেন সেটি আগে থেকেই আছে।	ক্লায়েন্ট সংক্রান্ত সমস্যা: ডুপ্লিকেট রিসোর্স তৈরি করা এড়িয়ে চলুন। রিসোর্স তৈরি করার চেষ্টা করার আগে সেটি আছে কিনা তা চেক করুন।
7	403	PERMISSION_DENIED	নির্দিষ্ট অপারেশনটি কার্যকর করার জন্য কলারের কাছে অনুমতি নেই।	ক্লায়েন্ট সংক্রান্ত সমস্যা: Google Ads অ্যাকাউন্টের জন্য যাচাইকরণ, অনুমোদন ও ব্যবহারকারীর ভূমিকা চেক করুন। অনুমতি সংক্রান্ত সমস্যার সমাধান না করে আবার চেষ্টা করবেন না।
8	429	RESOURCE_EXHAUSTED	হয় কোনও রিসোর্স শেষ হয়ে গেছে (যেমন, আপনি কোটা পেরিয়ে গেছেন) অথবা সিস্টেম ওভারলোড হয়ে গেছে।	ক্লায়েন্ট/সার্ভার সংক্রান্ত সমস্যা: সাধারণত অপেক্ষা করতে হয়। এক্সপোনেনশিয়াল ব্যাকঅফ প্রয়োগ করুন এবং অনুরোধের হার কমানোর চেষ্টা করুন। API-এর সীমা ও কোটা দেখুন।
9	400	FAILED_PRECONDITION	অপারেশনটি বাতিল করা হয়েছে কারণ সিস্টেমটি এমন অবস্থায় নেই যা অপারেশনটি কার্যকর করার জন্য প্রয়োজন। যেমন, কোনও প্রয়োজনীয় ফিল্ড ফাঁকা আছে।	ক্লায়েন্ট সংক্রান্ত সমস্যা: অনুরোধটি সঠিক, কিন্তু স্টেট ভুল। পূর্বশর্ত পূরণ না হওয়ার কারণ বুঝতে সমস্যার বিবরণ পর্যালোচনা করুন। স্ট্যাটাস সংশোধন না করে আবার চেষ্টা করবেন না।
10	409	ABORTED	অপারেশনটি বাতিল করা হয়েছে, সাধারণত ট্রানজ্যাকশন সংক্রান্ত বিরোধের মতো কনকারেন্সি সমস্যার কারণে।	সার্ভার সংক্রান্ত সমস্যা: সাধারণত অল্প সময় পরে আবার চেষ্টা করলে কাজ হয়।
11	400	OUT_OF_RANGE	সঠিক রেঞ্জের বাইরে অপারেশনটি করার চেষ্টা করা হয়েছে।	ক্লায়েন্ট সংক্রান্ত সমস্যা: রেঞ্জ বা ইন্ডেক্স ঠিক করুন।
12	501	UNIMPLEMENTED	অপারেশনটি API দ্বারা প্রয়োগ করা হয়নি বা কাজ করে না।	ক্লায়েন্ট সংক্রান্ত সমস্যা: API ভার্সন ও উপলভ্য ফিচার চেক করুন। আবার চেষ্টা করবেন না।
13	500	INTERNAL	কোনও ইন্টার্নাল সমস্যা হয়েছে। সার্ভার-সাইড সংক্রান্ত সমস্যার জন্য এটি একটি সাধারণ ক্যাচ-অল।	সার্ভারের সমস্যা: সাধারণত এক্সপোনেনশিয়াল ব্যাকঅফ-এর মাধ্যমে আবার চেষ্টা করা যেতে পারে। সমস্যাটি থেকে গেলে, সমস্যাটি সম্পর্কে অভিযোগ জানান।
14	503	UNAVAILABLE	পরিষেবা সাময়িকভাবে উপলভ্য নেই। এটি সম্ভবত একটি ক্ষণস্থায়ী অবস্থা।	সার্ভার সংক্রান্ত সমস্যা: এক্সপোনেনশিয়াল ব্যাকঅফ ব্যবহার করে আবার চেষ্টা করার জন্য বিশেষভাবে সাজেস্ট করা হচ্ছে।
15	500	DATA_LOSS	ডেটা ফিরিয়ে আনা যাবে না বা ডেটা নষ্ট হয়ে গেছে।	সার্ভারের সমস্যা: বিরল। গুরুতর সমস্যা নির্দেশ করে। আবার চেষ্টা করবেন না। সমস্যাটি থেকে গেলে, সমস্যাটি সম্পর্কে অভিযোগ জানান।
16	401	UNAUTHENTICATED	অনুরোধে সঠিক যাচাইকরণ সংক্রান্ত ক্রেডেনশিয়াল নেই।	ক্লায়েন্ট সংক্রান্ত সমস্যা: আপনার যাচাইকরণ টোকেন ও ক্রেডেনশিয়াল যাচাই করুন। যাচাইকরণ সংক্রান্ত সমস্যার সমাধান না করে আবার চেষ্টা করবেন না।

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

সমস্যার বিবরণ সম্পর্কে বুঝুন

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

প্রতিটি GoogleAdsFailure অবজেক্টে এগুলি থাকে:

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

প্রতিটি GoogleAdsError অবজেক্ট এগুলি প্রদান করে:

• error_code: আরও গ্র্যানুলার, Google Ads API-নির্দিষ্ট ErrorCode (সাধারণ সমস্যা), যেমন AuthenticationError.NOT_ADS_USER।
• message: নির্দিষ্ট সমস্যার মানুষের-পঠনযোগ্য বিবরণ।
• trigger: প্রযোজ্য হলে, যে Value-এর কারণে সমস্যা হয়েছে।
• location: একটি ErrorLocation যা অনুরোধের কোথায় সমস্যা হয়েছে তা বর্ণনা করে, যার মধ্যে ফিল্ড পাথও অন্তর্ভুক্ত।
• details: অতিরিক্ত ErrorDetails, যেমন, প্রকাশ না করার কারণ।

সমস্যার বিবরণের উদাহরণ

আপনি কোনও সমস্যার মেসেজ পেলে, আপনার ক্লায়েন্ট লাইব্রেরি আপনাকে এইসব বিবরণ অ্যাক্সেস করার অনুমতি দেবে। যেমন, INVALID_ARGUMENT (কোড ৩)-এ GoogleAdsFailure-এর বিবরণ এইভাবে থাকতে পারে:

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v26.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 0 },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 0 },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ],
      "requestId": "AbCdEfGhIjKlMnOpQrStUv"
    }
  ]
}

এই উদাহরণে, টপ-লেভেল INVALID_ARGUMENT থাকা সত্ত্বেও, GoogleAdsFailure বিবরণ থেকে আপনি জানতে পারবেন যে name এবং description ফিল্ডের কারণে সমস্যা হয়েছে এবং কেন হয়েছে (যথাক্রমে REQUIRED এবং TOO_SHORT)।

সমস্যার বিবরণ খুঁজে পাওয়া

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

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

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

আংশিক কাজ করেনি

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

ব্যাচ জব

ব্যাচ প্রসেসিং-এর জন্য, কাজ সম্পূর্ণ হওয়ার পরে BatchJobService.ListBatchJobResults-এ কল করে আলাদা আলাদা অপারেশনের জন্য সমস্যা খুঁজে পাওয়া যেতে পারে। প্রতিটি অপারেশন ফলাফলে একটি 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-এর মধ্যে গ্র্যানুলার error_code, 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. সম্পূর্ণ লগ: সমস্ত বিবরণ সহ সম্পূর্ণ ত্রুটি প্রতিক্রিয়া লগ করুন, বিশেষ করে অনুরোধ আইডি। ডিবাগিংয়ের জন্য এবং প্রয়োজন হলে Google সহায়তা টিমের কাছে সমস্যা রিপোর্ট করার জন্য এই তথ্য অত্যন্ত গুরুত্বপূর্ণ।

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

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