رسیدگی به پاسخ‌های خطا

این راهنما نحوه رسیدگی به خطاهای برگردانده‌شده توسط Merchant API را توضیح می‌دهد. درک ساختار و پایداری پاسخ خطا برای ساختن ادغام‌های قوی که می‌توانند به‌طور خودکار از خرابی‌ها بازیابی شوند یا بازخورد معنی‌داری به کاربران ارائه دهند، بسیار مهم است.

نمای کلی

وقتی درخواست Merchant API ناموفق باشد، میانای برنامه‌سازی کاربردی یک رمز وضعیت HTTP استاندارد (4xx یا 5xx) و یک بدنه پاسخ JSON حاوی جزئیات مربوط به خطا را برمی‌گرداند. Merchant API از استاندارد AIP-193 برای جزئیات خطا پیروی می‌کند و اطلاعات ماشین‌خوانایی ارائه می‌دهد که به برنامه شما امکان می‌دهد سناریوهای خطای خاص را به‌صورت برنامه‌ریزی‌شده مدیریت کند.

توجه: این ساختار پاسخ خطا به‌تدریج در Merchant API عرضه می‌شود. فقط خطاهای برگردانده‌شده توسط زیرمیاناهای برنامه‌سازی کاربردی «محصولات»، «گزارش‌ها»، و «منابع داده» از قالب شرح‌داده‌شده در اینجا پیروی می‌کنند. خطاهای سایر میاناهای برنامه‌سازی کاربردی فرعی ممکن است همچنان در قالب قدیمی باشند و ممکن است شامل فراداده‌های ErrorInfo نباشند.

ساختار پاسخ خطا

پاسخ خطا یک شیء JSON است که حاوی فیلدهای استاندارد مانند code، message، و status است. مهم‌تر از همه، این دستگاه دارای آرایه details است. برای رسیدگی به خطاها به‌صورت برنامه‌نویسی‌شده، باید به‌دنبال شیئی در details بگردید که @type آن type.googleapis.com/google.rpc.ErrorInfo باشد.

این شیء ErrorInfo داده‌های پایدار و ساختاریافته‌ای درباره خطا ارائه می‌دهد:

• domain: گروه‌بندی منطقی خطا، معمولاً merchantapi.googleapis.com.
• metadata: نقشه‌ای از مقادیر پویا مربوط به خطا. این شامل موارد زیر می‌شود:
  • REASON: شناسه خاص و ثابتی برای خطای دقیق (مثلاً INVALID_NAME_PART_NOT_NUMBER، PERMISSION_DENIED_ACCOUNTS). این فیلد همیشه وجود دارد. از این فیلد برای رسیدگی به خطاهای جزئی در منطق برنامه‌تان استفاده کنید.
  • HELP_CENTER_LINK: بافت و دستورالعمل‌های بیشتری برای رفع مشکل ارائه می‌دهد. این فیلد برای همه خطاها وجود ندارد، اما قصد داریم به‌مرور زمان پوشش آن را برای خطاهایی که ممکن است به بافت بیشتری نیاز داشته باشند گسترش دهیم.
  • فیلدهای پویای دیگر: کلیدهای دیگری که بافت ارائه می‌دهند، مثل نام فیلد نامعتبر (FIELD_LOCATION) یا مقداری که باعث خطا شده است (FIELD_VALUE).

پاسخ‌های خطای نمونه

JSON زیر ساختار خطای Merchant API را نشان می‌دهد که در آن نام منبع بدشکل است.

{
  "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: کلیدهای موجود در نقشه فراداده (برای مثال، FIELD_LOCATION، ACCOUNT_IDS) پایدار هستند.
  • code: رمز وضعیت HTTP سطح بالا (مثلاً 400، 401، 503) پایدار است.

• فیلدهای ناپایدار:

  • message: پیام خطای قابل‌خواندن برای انسان پایدار نیست. این فقط برای اشکال‌زدایی توسعه‌دهنده درنظر گرفته شده است. کدی ننویسید که محتوای نوشتاری فیلد message را تجزیه کند یا به آن متکی باشد، زیرا ممکن است این محتوا بدون اطلاع قبلی برای بهبود وضوح یا افزودن بافت تغییر کند.
  • details.metadata مقادیر: درحالی‌که کلیدها ثابت هستند، مقادیر کلیدهای اطلاعاتی ممکن است تغییر کنند. برای مثال، اگر کلید HELP_CENTER_LINK ارائه شود، نشانی وب خاصی که به آن اشاره می‌کند ممکن است بدون اطلاع قبلی به صفحه مستندات جدیدتری به‌روز شود. بااین‌حال، همان‌طور که قبلاً ذکر شد، مقدار details.metadata.REASON پایدار است.

روال‌های مطلوب

این روال‌های مطلوب را دنبال کنید تا مطمئن شوید هم‌آمیزی شما خطاها را به‌درستی مدیریت می‌کند.

استفاده از details.metadata.REASON برای منطق

همیشه از REASON خاص داخل نقشه metadata برای تعیین علت خطا استفاده کنید. فقط به کد وضعیت HTTP اتکا نکنید، زیرا ممکن است چندین خطا کد وضعیت یکسانی داشته باشند.

پیام خطا تجزیه نشود

همان‌طور که در بخش پایداری ذکر شد، فیلد message برای استفاده انسان است. اگر به اطلاعات پویا نیاز دارید (مثلاً اینکه کدام فیلد نامعتبر بود)، آن را بااستفاده از کلیدهای پایدار مثل FIELD_LOCATION، VARIABLE_NAME از نقشه metadata استخراج کنید.

پیاده‌سازی عقب‌گرد نمایی

برای خطاهایی که نشان‌دهنده عدم دسترسی موقت یا محدودیت نرخ هستند، یک استراتژی عقب‌نشینی نمایی را پیاده‌سازی کنید. این یعنی قبل‌از امتحان مجدد، مدت کوتاهی صبر کنید و با هر بار ناموفق بودن، زمان انتظار را افزایش دهید.

• quota/request_rate_too_high: این خطا نشان می‌دهد که از سهمیه دقیقه‌ای خود برای گروه سهمیه خاصی فراتر رفته‌اید. نرخ درخواستتان را کاهش دهید.
• ‫internal_error: این‌ها معمولاً گذرا هستند. با عقب‌گرد نمایی دوباره امتحان کنید.

توجه: اگر internal_error پس‌از چندبار امتحان مجدد با عقب‌نشینی همچنان ادامه داشت، به نحوه تماس با پشتیبانی Merchant API مراجعه کنید.

نحوه تماس با پشتیبانی Merchant API

اگر لازم است برای خطای خاصی با پشتیبانی Merchant API تماس بگیرید، اطلاعات زیر را در درخواستتان ارائه دهید:

1. پاسخ خطای دقیق دریافت شد
2. نام روش میانای برنامه‌سازی کاربردی
3. پایه‌بار درخواست
4. مُهرهای زمان یا محدوده زمانی که طی آن روش فراخوانی شده و خطاها دریافت شده‌اند