ত্রুটির প্রতিক্রিয়াগুলি পরিচালনা করুন

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

সংক্ষিপ্ত বিবরণ

যখন কোনো মার্চেন্ট এপিআই অনুরোধ ব্যর্থ হয়, তখন এপিআই একটি স্ট্যান্ডার্ড HTTP স্ট্যাটাস কোড ( 4xx বা 5xx ) এবং ত্রুটি সম্পর্কিত বিবরণ সম্বলিত একটি JSON রেসপন্স বডি ফেরত দেয়। মার্চেন্ট এপিআই ত্রুটির বিবরণের জন্য AIP-193 স্ট্যান্ডার্ড অনুসরণ করে, যা মেশিন-পঠনযোগ্য তথ্য সরবরাহ করে এবং আপনার অ্যাপ্লিকেশনকে প্রোগ্রাম্যাটিকভাবে নির্দিষ্ট ত্রুটির পরিস্থিতি সামাল দিতে সক্ষম করে।

ত্রুটি প্রতিক্রিয়া কাঠামো

এরর রেসপন্সটি একটি JSON অবজেক্ট, যাতে code , message , এবং status মতো স্ট্যান্ডার্ড ফিল্ডগুলো থাকে। গুরুত্বপূর্ণভাবে, এতে একটি details অ্যারেও অন্তর্ভুক্ত থাকে। প্রোগ্রাম্যাটিকভাবে এরর হ্যান্ডেল করার জন্য, আপনাকে details মধ্যে এমন একটি অবজেক্ট খুঁজতে হবে, যার @type হলো type.googleapis.com/google.rpc.ErrorInfo ।

এই ErrorInfo অবজেক্টটি ত্রুটি সম্পর্কে স্থিতিশীল ও সুসংগঠিত ডেটা প্রদান করে:

  • ডোমেইন : ত্রুটির যৌক্তিক গোষ্ঠী, সাধারণত merchantapi.googleapis.com ।
  • মেটাডেটা : ত্রুটি সম্পর্কিত পরিবর্তনশীল মানগুলোর একটি মানচিত্র। এর মধ্যে অন্তর্ভুক্ত রয়েছে:
    • কারণ : সঠিক ত্রুটির জন্য একটি সুনির্দিষ্ট, স্থিতিশীল শনাক্তকারী (যেমন, INVALID_NAME_PART_NOT_NUMBER , PERMISSION_DENIED_ACCOUNTS )। এই ফিল্ডটি সর্বদা উপস্থিত থাকে। আপনার অ্যাপ্লিকেশন লজিকে সূক্ষ্ম ত্রুটি ব্যবস্থাপনার জন্য এই ফিল্ডটি ব্যবহার করুন।
    • হেল্প সেন্টার লিঙ্ক : সমস্যাটি সমাধানের জন্য অতিরিক্ত প্রাসঙ্গিক তথ্য এবং নির্দেশাবলী প্রদান করে। এই ক্ষেত্রটি সব ত্রুটির জন্য উপস্থিত থাকে না, তবে আমরা সময়ের সাথে সাথে সেইসব ত্রুটির জন্য এর পরিধি প্রসারিত করার পরিকল্পনা করছি যেখানে আরও প্রাসঙ্গিক তথ্যের প্রয়োজন হতে পারে।
    • অন্যান্য ডাইনামিক ফিল্ড : প্রাসঙ্গিকতা প্রদানকারী অন্যান্য কী, যেমন অবৈধ ফিল্ডের নাম ( FIELD_LOCATION ) অথবা যে মানের কারণে ত্রুটি ঘটেছে ( FIELD_VALUE )।

নমুনা ত্রুটির প্রতিক্রিয়া

নিম্নলিখিত JSON-টি একটি মার্চেন্ট এপিআই ত্রুটির কাঠামো প্রদর্শন করে, যেখানে একটি রিসোর্সের নাম ভুলভাবে গঠিত হয়েছিল।

{
  "error": {
    "code": 400,
    "message": "[name] The part `account` of the resource name in field `name` must be a number, but has value: `abcd`.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "VARIABLE_NAME": "account",
          "FIELD_LOCATION": "name",
          "FIELD_VALUE": "abcd",
          "REASON": "INVALID_NAME_PART_NOT_NUMBER"
        }
      }
    ]
  }
}

এখানে একটি প্রমাণীকরণ ত্রুটির উদাহরণ দেওয়া হলো:

{
  "error": {
    "code": 401,
    "message": "The caller does not have access to the accounts: [1234567]",
    "status": "UNAUTHENTICATED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "unauthorized",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_IDS": "[1234567]",
          "REASON": "PERMISSION_DENIED_ACCOUNTS"
        }
      }
    ]
  }
}

ত্রুটি ক্ষেত্রের স্থিতিশীলতা

এরর হ্যান্ডলিং লজিক লেখার সময়, কোন ফিল্ডগুলোর ওপর নিরাপদে নির্ভর করা যায় এবং কোনগুলো পরিবর্তিত হতে পারে, তা জানা জরুরি।

  • স্থিতিশীল ক্ষেত্র:

  • details.metadata.REASON : নির্দিষ্ট ত্রুটি শনাক্তকারী। আপনার অ্যাপ্লিকেশনের নিয়ন্ত্রণ প্রবাহ যুক্তির জন্য এই ক্ষেত্রটির উপর নির্ভর করা উচিত।

    • details.metadata keys : মেটাডেটা ম্যাপের অন্তর্গত কীগুলি (যেমন, FIELD_LOCATION , ACCOUNT_IDS ) স্থিতিশীল।
    • code : উচ্চ-স্তরের HTTP স্ট্যাটাস কোডটি (যেমন, 400 , 401 , 503 ) স্থিতিশীল।

  • অস্থিতিশীল ক্ষেত্র:

    • message : পাঠযোগ্য ত্রুটির বার্তাটি স্থিতিশীল নয় । এটি শুধুমাত্র ডেভেলপারদের ডিবাগিংয়ের জন্য উদ্দিষ্ট। এমন কোনো কোড লিখবেন না যা message ফিল্ডের টেক্সট কন্টেন্ট পার্স করে বা তার উপর নির্ভর করে , কারণ স্পষ্টতা বাড়াতে বা প্রাসঙ্গিকতা যোগ করতে এটি কোনো বিজ্ঞপ্তি ছাড়াই পরিবর্তিত হতে পারে।
    • details.metadata মানসমূহ : যদিও কী-গুলো স্থিতিশীল, তথ্যমূলক কী-গুলোর মান পরিবর্তিত হতে পারে। উদাহরণস্বরূপ, যদি একটি HELP_CENTER_LINK কী প্রদান করা হয়, তবে এটি যে নির্দিষ্ট URL-টিকে নির্দেশ করে, তা পূর্ব বিজ্ঞপ্তি ছাড়াই একটি নতুন ডকুমেন্টেশন পৃষ্ঠায় আপডেট করা হতে পারে। তবে, যেমনটি আগে উল্লেখ করা হয়েছে, details.metadata.REASON এর মান স্থিতিশীল।

সর্বোত্তম অনুশীলন

আপনার ইন্টিগ্রেশন যেন ত্রুটিগুলো সুষ্ঠুভাবে সামাল দিতে পারে, তা নিশ্চিত করতে এই সর্বোত্তম পদ্ধতিগুলো অনুসরণ করুন।

লজিকের জন্য details.metadata.REASON ব্যবহার করুন

কোনো ত্রুটির কারণ নির্ধারণ করতে সর্বদা metadata ম্যাপের মধ্যে থাকা নির্দিষ্ট REASON ব্যবহার করুন। শুধুমাত্র HTTP স্ট্যাটাস কোডের উপর নির্ভর করবেন না, কারণ একাধিক ত্রুটির একই স্ট্যাটাস কোড থাকতে পারে।

ত্রুটির বার্তাটি বিশ্লেষণ করবেন না।

স্থিতিশীলতা বিভাগে যেমন উল্লেখ করা হয়েছে, message ফিল্ডটি মানুষের পড়ার জন্য। আপনার যদি পরিবর্তনশীল তথ্যের (যেমন কোন ফিল্ডটি অবৈধ ছিল) প্রয়োজন হয়, তবে FIELD_LOCATION , VARIABLE_NAME মতো স্থিতিশীল কী ব্যবহার করে metadata ম্যাপ থেকে তা সংগ্রহ করুন।

এক্সপোনেনশিয়াল ব্যাকঅফ প্রয়োগ করুন

সাময়িক অনুপলব্ধতা বা রেট লিমিটিং নির্দেশকারী ত্রুটির ক্ষেত্রে, একটি এক্সপোনেনশিয়াল ব্যাকঅফ কৌশল প্রয়োগ করুন। এর অর্থ হলো, পুনরায় চেষ্টা করার আগে অল্প কিছুক্ষণ অপেক্ষা করা এবং প্রতিটি পরবর্তী ব্যর্থতার সাথে অপেক্ষার সময় বাড়ানো।

  • quota/request_rate_too_high : এই ত্রুটিটি নির্দেশ করে যে আপনি একটি নির্দিষ্ট কোটা গ্রুপের জন্য আপনার মিনিটের কোটা অতিক্রম করেছেন। আপনার অনুরোধের হার কমিয়ে দিন।
  • internal_error : এগুলি সাধারণত ক্ষণস্থায়ী। এক্সপোনেনশিয়াল ব্যাকঅফ সহ পুনরায় চেষ্টা করুন। দ্রষ্টব্য: ব্যাকঅফ সহ একাধিকবার চেষ্টা করার পরেও যদি internal_error থেকে যায়, তাহলে মার্চেন্ট এপিআই সাপোর্টের সাথে কীভাবে যোগাযোগ করবেন তা দেখুন।

মার্চেন্ট এপিআই সাপোর্টের সাথে কীভাবে যোগাযোগ করবেন

কোনো নির্দিষ্ট ত্রুটি সম্পর্কে মার্চেন্ট এপিআই সাপোর্টের সাথে যোগাযোগ করতে হলে, আপনার অনুরোধে নিম্নলিখিত তথ্যগুলো প্রদান করুন:

  1. প্রাপ্ত সঠিক ত্রুটি প্রতিক্রিয়া
  2. এপিআই পদ্ধতির নাম
  3. অনুরোধ পেলোড
  4. টাইমস্ট্যাম্প অথবা সেই সময়সীমা যার মধ্যে মেথডটি কল করা হয়েছিল এবং ত্রুটিগুলো পাওয়া গিয়েছিল।