Menangani respons error

Panduan ini menjelaskan cara menangani error yang ditampilkan oleh Merchant API. Memahami struktur dan stabilitas respons error sangat penting untuk membangun integrasi yang kuat yang dapat otomatis pulih dari kegagalan atau memberikan masukan yang bermakna kepada pengguna.

Ringkasan

Jika permintaan Merchant API gagal, API akan menampilkan kode status HTTP standar (4xx atau 5xx) dan isi respons JSON yang berisi detail tentang error tersebut. Merchant API mengikuti standar AIP-193 untuk detail error, yang memberikan informasi yang dapat dibaca mesin sehingga aplikasi Anda dapat menangani skenario error tertentu secara terprogram.

Struktur respons error

Respons error adalah objek JSON yang berisi kolom standar seperti code, message, dan status. Yang penting, respons error juga menyertakan array details. Untuk menangani error secara terprogram, Anda harus mencari objek dalam details dengan @type adalah type.googleapis.com/google.rpc.ErrorInfo.

Objek ErrorInfo ini menyediakan data terstruktur yang stabil tentang error:

• domain: Pengelompokan logis error, biasanya merchantapi.googleapis.com.
• metadata: Peta nilai dinamis yang terkait dengan error. Hal ini mencakup:
  • REASON: ID spesifik dan stabil untuk error yang tepat (misalnya, INVALID_NAME_PART_NOT_NUMBER, PERMISSION_DENIED_ACCOUNTS). Kolom ini selalu ada. Gunakan kolom ini untuk penanganan error yang lebih mendetail dalam logika aplikasi Anda.
  • HELP_CENTER_LINK: Memberikan konteks dan petunjuk tambahan untuk memperbaiki masalah. Kolom ini tidak ada untuk semua error, tetapi kami berencana untuk memperluas cakupannya dari waktu ke waktu untuk error yang mungkin memerlukan lebih banyak konteks.
  • Kolom dinamis lainnya: Kunci lain yang memberikan konteks, seperti nama kolom yang tidak valid (FIELD_LOCATION) atau nilai yang menyebabkan error (FIELD_VALUE).

Contoh respons error

JSON berikut menunjukkan struktur error Merchant API saat nama resource salah format.

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

Berikut adalah contoh error autentikasi:

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

Stabilitas kolom error

Saat menulis logika penanganan error, penting untuk mengetahui kolom mana yang aman untuk diandalkan dan mana yang mungkin berubah.

• Kolom stabil:

• details.metadata.REASON: ID error tertentu. Anda harus mengandalkan kolom ini untuk logika alur kontrol aplikasi Anda.

  • Kunci details.metadata: Kunci dalam peta metadata (misalnya, FIELD_LOCATION, ACCOUNT_IDS) bersifat stabil.
  • code: Kode status HTTP tingkat tinggi (misalnya, 400, 401, 503) bersifat stabil.

• Kolom tidak stabil:

  • message: Pesan error yang dapat dibaca manusia tidak stabil. Pesan ini hanya ditujukan untuk proses debug developer. Jangan menulis kode yang mengurai atau mengandalkan konten teks kolom message field, karena kode tersebut dapat berubah tanpa pemberitahuan untuk meningkatkan kejelasan atau menambahkan konteks.
  • Nilai details.metadata: Meskipun kunci bersifat stabil, nilai untuk kunci informasi dapat berubah. Misalnya, jika kunci HELP_CENTER_LINK diberikan, URL tertentu yang ditujunya mungkin diperbarui ke halaman dokumentasi yang lebih baru tanpa pemberitahuan sebelumnya. Namun, seperti yang disebutkan sebelumnya, nilai details.metadata.REASON bersifat stabil.

Praktik terbaik

Ikuti praktik terbaik berikut untuk memastikan integrasi Anda menangani error dengan baik.

Menggunakan details.metadata.REASON untuk logika

Selalu gunakan REASON tertentu di dalam peta metadata untuk menentukan penyebab error. Jangan hanya mengandalkan kode status HTTP, karena beberapa error dapat menggunakan kode status yang sama.

Jangan mengurai pesan error

Seperti yang disebutkan di bagian stabilitas, kolom message ditujukan untuk penggunaan manusia. Jika Anda memerlukan informasi dinamis (seperti kolom mana yang tidak valid), ekstrak informasi tersebut dari peta metadata menggunakan kunci stabil seperti FIELD_LOCATION, VARIABLE_NAME.

Menerapkan backoff eksponensial

Untuk error yang menunjukkan ketidaktersediaan sementara atau pembatasan frekuensi, terapkan strategi backoff eksponensial. Artinya, tunggu sebentar sebelum mencoba lagi, dan tingkatkan waktu tunggu dengan setiap kegagalan berikutnya.

• quota/request_rate_too_high: Error ini menunjukkan bahwa Anda telah melampaui kuota menit untuk grup kuota tertentu. Perlambat frekuensi permintaan Anda.
• internal_error: Error ini biasanya bersifat sementara. Coba lagi dengan backoff eksponensial. Catatan: Jika internal_error berlanjut setelah beberapa kali mencoba lagi dengan backoff, lihat Cara menghubungi dukungan Merchant API support.

Cara menghubungi dukungan Merchant API

Jika Anda perlu menghubungi dukungan Merchant API terkait error tertentu, berikan informasi berikut dalam permintaan Anda:

1. Respons error yang tepat diterima
2. Nama metode API
3. Payload permintaan
4. Stempel waktu atau rentang waktu saat metode dipanggil dan error diterima