کدهای خطا

این صفحه کدهای خطای متعارفی را که باید هنگام ادغام با گوگل با استفاده از پروتکل تجارت جهانی (UCP) در پاسخ‌های API خود برگردانید، شرح می‌دهد. کدهای خطای سازگار، ارتباط واضح را تضمین می‌کنند و به گوگل کمک می‌کنند تا سناریوهای مختلف را به طور مناسب مدیریت کند.

وقتی یک خطای تجاری رخ می‌دهد، API شما باید یک پیام پاسخ برگرداند که شامل code مناسب از جدول باشد. برای برخی از کدهای خطا، یک ساختار JSON خاص برای آرایه messages در پاسخ توصیه می‌شود. این مثال‌ها در بخش نمونه‌های کد خطا در زیر جدول ارائه شده‌اند. در این مثال‌ها، شما باید از فیلد path برای ارائه اطلاعات دقیق‌تر در مورد محل خطا در شیء درخواست یا پاسخ استفاده کنید.

مدیریت خطا

نحوه گزارش خطاها به نوع خطا بستگی دارد:

  • خطاهای پروتکل/سرور:

    • برای مشکلاتی مانند درخواست‌های ناقص، خطاهای احراز هویت یا عدم دسترسی به سرور، از کدهای وضعیت استاندارد HTTP (مثلاً 4xx برای خطاهای کلاینت، 5xx برای خطاهای سرور) استفاده کنید.
    • برای جزئیات بیشتر به مشخصات UCP مراجعه کنید.

  • خطاها/هشدارهای منطق کسب و کار:

    • وضعیت HTTP 200 OK را برمی‌گرداند.
    • مشکل را در آرایه messages در بدنه پاسخ JSON شرح دهید.
    • هر شیء در آرایه messages باید شامل موارد زیر باشد:
      • type : "error" یا "warning"
      • code : یک کد استاندارد از این راهنما. از کدهای عمومی یا ناشناخته مانند "invalid" استفاده نکنید.
      • content : توضیحی قابل خواندن توسط انسان.
      • severity : زمانی که type "error" باشد، الزامی است. این فیلد به صراحت نشان می‌دهد که آیا خطا نهایی ( unrecoverable ) است یا به شما امکان می‌دهد به جای تکیه بر خود کد خطا، از خریدار بخواهید مشکل را اصلاح کند ( recoverable ).

انواع پیام: خطا در مقابل هشدار

فیلد type در آرایه پیام، شدت مشکل را نشان می‌دهد. UCP دو نوع اصلی را تعریف می‌کند:

  • error : نشان می‌دهد که عملیات درخواستی نتوانسته تکمیل شود. احتمالاً پلتفرم یا کاربر باید اقدامی انجام دهد و دوباره امتحان کند. به مشخصات پیام-خطا مراجعه کنید.
    • ماهیت نهایی یک خطا توسط فیلد severity ( unrecoverable یا recoverable ) تعیین می‌شود، نه code خطا.
  • warning : نشان می‌دهد که عملیات مسدود نشده است، اما نکته‌ی قابل توجهی وجود دارد که باید به کاربر اطلاع داده شود. این روند را متوقف نمی‌کند اما زمینه‌ی مهمی را فراهم می‌کند. به مشخصات هشدار پیام مراجعه کنید.

مرجع کد خطا

کد خطا نوع توصیه شده توضیحات
out_of_stock خطا کالا موجود نیست. این معمولاً منجر به خطای ucp.status: “error” می‌شود. از فیلد path برای نشان دادن اندیس کالا در پرداخت‌های چند کالایی استفاده کنید. به مثال زیر توجه کنید.
item_unavailable خطا مورد یافت نشد. این معمولاً منجر به خطای ucp.status: “error” برای این خطاهای مربوط به مورد می‌شود.
item_ineligible خطا کالا موجود است اما نمی‌توان آن را با استفاده از UCP خریداری کرد.
quantity_invalid_limit_exceeded خطا مقدار درخواستی از حد مجاز بیشتر است. به مثال زیر مراجعه کنید.
quantity_invalid_minimum_not_met خطا تعداد درخواستی کمتر از حداقل مورد نیاز است.
totals_changed هشدار قیمت یا سایر مبالغ از آخرین مرحله تغییر کرده‌اند. از فیلد path برای نشان دادن اینکه کدام مبلغ تغییر کرده است استفاده کنید. به مثال زیر مراجعه کنید.
totals_invalid_minimum_not_met خطا مبلغ سفارش حداقل مورد نیاز را برآورده نمی‌کند.
missing_buyer_info خطا اطلاعات مورد نیاز خریدار موجود نیست. از فیلد path برای مشخص کردن فیلد موجود استفاده کنید. به مثال زیر توجه کنید.
address_undeliverable خطا این یک کد خطای استاندارد UCP است. از فیلد path برای مشخص کردن مقصد خاص یا مورد محدود شده استفاده کنید. به مثال زیر مراجعه کنید.
address_unverifiable خطا آدرس ارائه شده قابل تأیید نیست. از فیلد path برای مشخص کردن اینکه آیا آدرس مربوط به انجام سفارش است یا آدرس مربوط به صدور صورتحساب استفاده کنید. به مثال زیر توجه کنید.
missing_fulfillment_info خطا اطلاعات مورد نیاز برای تکمیل سفارش موجود نیست. از فیلد path برای مشخص کردن فیلد موجود استفاده کنید.
eligibility_invalid خطا کاربر یا سفارش واجد شرایط این اقدام نیست. این یک کد خطای استاندارد UCP است. برای جزئیات از فیلد path استفاده کنید.
discount_code_invalid هشدار کد تخفیف نامعتبر است. کد یافت نشد یا ناقص وارد شده است.
discount_code_expired هشدار کد تخفیف منقضی شده است.
discount_code_already_applied هشدار کد تخفیف قبلاً اعمال شده است.
discount_code_combination_disallowed هشدار کد تخفیف را نمی‌توان با سایر پیشنهادات ترکیب کرد.
discount_code_user_not_logged_in هشدار کاربر برای استفاده از کد تخفیف باید وارد سیستم شود.
discount_code_user_ineligible هشدار کاربر مورد نظر مجاز به استفاده از کد تخفیف نیست.
missing_billing_info خطا اطلاعات صورتحساب مورد نیاز موجود نیست. از فیلد path برای مشخص کردن فیلدهای آدرس صورتحساب موجود استفاده کنید. به مثال زیر مراجعه کنید.
identity_required خطا هویت کاربر برای عملیات درخواستی لازم است، اما وجود نداشته، نامعتبر، منقضی شده یا غیرقابل تأیید بوده است. برای REST، از کد وضعیت ۴۰۱ استفاده کنید. به مثال زیر مراجعه کنید.
insufficient_scope خطا توکن هویت کاربر معتبر است اما فاقد محدوده(های) مورد نیاز عملیات است. برای REST، از کد وضعیت ۴۰۳ استفاده کنید. به مثال زیر مراجعه کنید.
payment_declined خطا پرداخت توسط صادرکننده کارت یا بانک رد شده است. دلایل می‌تواند شامل موجودی ناکافی، مشکوک به کلاهبرداری یا مشکلات کارت باشد. به مثال زیر مراجعه کنید.
payment_failed خطا پرداخت به دلیل یک مشکل فنی در حین پردازش - مانند خطای شبکه، اتمام زمان درگاه یا مشکل ادغام - که مانع از تصمیم‌گیری بانک شد، انجام نشد.
payment_ineligible خطا روش پرداخت انتخاب شده پذیرفته نمی‌شود. مناسب برای مواردی که کاربر نیاز به امتحان کردن روش پرداخت متفاوتی دارد.
rejected_for_fraud خطا این سفارش به دلیل مشکوک بودن به تقلب رد شد.

مثال‌های کد خطا

این بخش نمونه‌های JSON برای آرایه messages برای کدهای خطای خاص ارائه می‌دهد.

out_of_stock

پرداخت تکی کالا:

{
  "type": "error",
  "severity": "unrecoverable",
  "code": "out_of_stock",
  "content": "Unfortunately, the item 'Example Product 1' is out of stock."
}

پرداخت چند کالایی:

از فیلد path برای نشان دادن اندیس کالای خاصی که ناموجود است استفاده کنید.

{
  "type": "error",
  "severity": "recoverable",
  "code": "out_of_stock",
  "path": "$.checkout.line_items[1]",
  "content": "The item 'Example Product 2' is out of stock. Remove it from your cart to continue."
}

quantity_invalid_limit_exceeded 

{
  "type": "error",
  "severity": "recoverable",
  "code": "quantity_invalid_limit_exceeded",
  "path": "$.checkout.line_items[0].quantity",
  "content": "The requested quantity for 'Example Product 2' exceeds the maximum allowed limit of 5."
}

totals_changed 

{
  "type": "warning",
  "code": "totals_changed",
  "path": "$.totals[2]",
  "content": "Shipping cost has changed."
}

missing_buyer_info 

{
  "type": "error",
  "severity": "recoverable",
  "code": "missing_buyer_info",
  "path": "$.buyer.first_name",
  "content": "Missing buyer first name."
}

address_undeliverable

محدودیت در سطح سفارش (مثلاً کد پستی پشتیبانی نمی‌شود):

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_undeliverable",
  "content": "Delivery is not supported for the provided zipcode."
}

محدودیت در سطح آیتم:

از فیلد path برای مشخص کردن یک کالای خاص که نمی‌توان آن را به مقصد انتخاب شده تحویل داد (مثلاً ممنوعیت‌های خاص ایالت) استفاده کنید.

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_undeliverable",
  "path": "$.checkout.line_items[1]",
  "content": "The item 'Example Product 2' cannot be delivered to the selected address."
}

address_unverifiable

آدرس پرداخت صورتحساب:

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_unverifiable",
  "path": "$.payment.instruments[0].billing_address",
  "content": "Invalid billing address. Update the address before trying again."
}

آدرس محل تکمیل:

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_unverifiable",
  "path": "$.fulfillment.methods[0].destinations[0]",
  "content": "The fulfillment address couldn't be verified. Update the address and try again."
}

missing_billing_info

از فیلد path برای مشخص کردن فیلدهای جا افتاده در آدرس صورتحساب استفاده کنید. 

{
  "type": "error",
  "severity": "recoverable",
  "code": "missing_billing_info",
  "path": "$.payment.instruments[0].billing_address.street_address",
  "content": "Missing billing street address."
}

identity_required

در REST API، این خطا باید با کد وضعیت HTTP 401 برگردانده شود. 

{
  "type": "error",
  "severity": "requires_buyer_review",
  "code": "identity_required",
  "content": "User identity is required to access order history."
}

insufficient_scope

در REST API، این خطا باید با کد وضعیت HTTP 403 برگردانده شود. 

{
  "type": "error",
  "severity": "requires_buyer_review",
  "code": "insufficient_scope",
  "content": "This operation requires scopes: dev.ucp.shopping.order:read, dev.ucp.shopping.order:manage"
}

payment_declined 

{
  "type": "error",
  "severity": "recoverable",
  "code": "payment_declined",
  "path": "$.payment.instruments[0]",
  "content": "Payment was declined by the issuer. Try a different payment method or contact your bank."
}
قبلی
چرخه عمر سفارش (پس از خرید)