Kode error

Halaman ini menguraikan kode error kanonis yang harus Anda kembalikan dalam respons API saat berintegrasi dengan Google menggunakan Universal Commerce Protocol (UCP). Kode error yang konsisten memastikan komunikasi yang jelas dan membantu Google menangani berbagai skenario dengan tepat.

Saat terjadi error bisnis, API Anda harus menampilkan pesan respons yang mencakup code yang sesuai dari tabel. Untuk beberapa kode error, struktur JSON tertentu direkomendasikan untuk array messages dalam respons. Contoh ini disediakan di bagian Contoh kode error di bawah tabel. Dalam contoh ini, Anda harus menggunakan kolom path untuk memberikan informasi yang lebih spesifik tentang lokasi error dalam objek permintaan atau respons.

Penanganan Error

Cara melaporkan error bergantung pada jenis error:

• Error Protokol/Server:

  • Gunakan kode status HTTP standar (misalnya, 4xx untuk error klien, 5xx untuk error server) untuk masalah seperti permintaan yang salah format, kegagalan autentikasi, atau server tidak tersedia.
  • Lihat Spesifikasi UCP untuk mengetahui detailnya.

• Error/Peringatan Logika Bisnis:

  • Menampilkan status HTTP 200 OK. Hal ini mencakup penolakan pembayaran dan penolakan penipuan, meskipun gateway pembayaran hilir Anda menampilkan error 4xx atau 5xx.
  • Jelaskan masalah dalam array messages di isi respons JSON.
  • Setiap objek dalam array messages harus menyertakan:
    • type: "error" atau "warning"
    • code: Kode standar dari panduan ini. Jangan gunakan kode umum atau tidak dikenal seperti "invalid".
    • content: Deskripsi yang dapat dibaca manusia.
    • severity: Diperlukan jika type adalah "error". Kolom ini secara eksplisit menunjukkan apakah error bersifat fatal (unrecoverable) atau memungkinkan Anda meminta pembeli untuk memperbaiki masalah (recoverable), bukan mengandalkan kode error itu sendiri.

Jenis pesan: Error versus peringatan

Kolom type dalam array pesan menunjukkan tingkat keparahan masalah. UCP menentukan dua jenis utama:

• error: Menunjukkan bahwa operasi yang diminta tidak dapat diselesaikan. Platform atau pengguna mungkin perlu mengambil tindakan dan mencoba lagi. Lihat spesifikasi message-error.
  • Sifat terminal error ditentukan oleh kolom severity (unrecoverable atau recoverable), bukan error code.
• warning: Menunjukkan bahwa operasi tidak diblokir, tetapi ada sesuatu yang penting yang harus dikomunikasikan kepada pengguna. Hal ini tidak menghentikan proses, tetapi memberikan konteks penting. Lihat spesifikasi message-warning.

Referensi kode error

Contoh kode error

Bagian ini memberikan contoh JSON untuk array messages untuk kode error tertentu.

out_of_stock

Checkout satu item:

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

Pembayaran multi-item:

Gunakan kolom path untuk menunjukkan indeks item tertentu yang kehabisan stok.

{
  "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

Pembatasan tingkat pesanan (misalnya, kode pos tidak didukung):

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

Pembatasan tingkat item:

Gunakan kolom path untuk menunjukkan item tertentu yang tidak dapat dikirim ke tujuan yang dipilih (misalnya, larangan khusus negara bagian).

{
  "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

Alamat penagihan:

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

Alamat pemenuhan pesanan:

{
  "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

Gunakan kolom path untuk menentukan kolom yang tidak ada dalam alamat penagihan.

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

identity_required

Di REST API, error ini harus ditampilkan dengan kode status HTTP 401.

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

insufficient_scope

Di REST API, error ini harus ditampilkan dengan kode status 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"
}

Error pembayaran

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."
}

rejected_for_fraud

{
  "type": "error",
  "severity": "recoverable",
  "code": "rejected_for_fraud",
  "path": "$.payment.instruments[0]",
  "content": "The order was rejected due to suspected fraud. Try a different payment method."
}