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 andal yang dapat pulih secara otomatis 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, objek ini juga menyertakan array details. Untuk menangani error secara terprogram, Anda harus mencari objek dalam details dengan @type yang 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 terperinci 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 seiring 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 kesalahan (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) sudah 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. Opsi ini hanya ditujukan untuk proses debug developer. Jangan menulis kode yang mengurai atau mengandalkan konten teks kolom message, karena konten tersebut dapat berubah tanpa pemberitahuan untuk meningkatkan kejelasan atau menambahkan konteks.
    • Nilai details.metadata: Meskipun kunci stabil, nilai untuk kunci informasi dapat berubah. Misalnya, jika kunci HELP_CENTER_LINK disediakan, URL tertentu yang ditujuknya dapat diperbarui ke halaman dokumentasi yang lebih baru tanpa pemberitahuan sebelumnya. Namun, seperti yang disebutkan sebelumnya, nilai details.metadata.REASON 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 memiliki kode status yang sama.

Jangan mengurai pesan error

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

Menerapkan backoff eksponensial

Untuk error yang menunjukkan tidak tersedianya layanan sementara atau pembatasan kecepatan, terapkan strategi backoff eksponensial. Artinya, tunggu sebentar sebelum mencoba lagi, dan tingkatkan waktu tunggu untuk setiap kegagalan berikutnya.

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

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