Error

Bab ini berisi ringkasan model error untuk Google API. Panduan ini juga memberikan panduan umum bagi developer tentang cara membuat dan menangani error dengan benar.

Google API menggunakan model error sederhana yang tidak bergantung pada protokol, yang memungkinkan kami menawarkan pengalaman yang konsisten di berbagai API, protokol API yang berbeda (seperti gRPC atau HTTP), dan konteks error yang berbeda (seperti error asinkron, batch, atau alur kerja).

Model Error

Model error untuk Google API ditentukan secara logis oleh google.rpc.Status, yang instancenya ditampilkan ke klien saat terjadi error API. Cuplikan kode berikut menunjukkan desain model error secara keseluruhan:

package google.rpc;

// The `Status` type defines a logical error model that is suitable for
// different programming environments, including REST APIs and RPC APIs.
message Status {
  // A simple error code that can be easily handled by the client. The
  // actual error code is defined by `google.rpc.Code`.
  int32 code = 1;

  // A developer-facing human-readable error message in English. It should
  // both explain the error and offer an actionable resolution to it.
  string message = 2;

  // Additional error information that the client code can use to handle
  // the error, such as retry info or a help link.
  repeated google.protobuf.Any details = 3;
}

Karena sebagian besar Google API menggunakan desain API berorientasi resource, penanganan error mengikuti prinsip desain yang sama, yaitu menggunakan sekumpulan kecil error standar dengan sejumlah besar resource. Misalnya, daripada menetapkan berbagai jenis error "tidak ditemukan", server menggunakan satu kode error google.rpc.Code.NOT_FOUND standar dan memberi tahu klien resource spesifik mana yang tidak ditemukan. Ruang error yang lebih kecil mengurangi kompleksitas dokumentasi, memberikan pemetaan idiomatis yang lebih baik dalam library klien, dan mengurangi kompleksitas logika klien sekaligus tidak membatasi penyertaan informasi yang dapat ditindaklanjuti.

Catatan: Saat menggunakan gRPC, error disertakan dalam header, dan total header dalam respons dibatasi hingga 8 KB (8.192 byte). Pastikan ukuran error tidak melebihi 1-2 KB.

Kode Error

Google API harus menggunakan kode error kanonis yang ditentukan oleh google.rpc.Code. Setiap API harus menghindari penetapan kode error tambahan, karena developer sangat tidak mungkin menulis logika untuk menangani kode error dalam jumlah besar. Sebagai referensi, menangani rata-rata tiga kode error per panggilan API berarti sebagian besar logika aplikasi hanya digunakan untuk penanganan error, yang bukanlah pengalaman developer yang baik.

Pesan Error

Pesan error akan membantu pengguna memahami dan mengatasi error API dengan mudah dan cepat. Secara umum, pertimbangkan panduan berikut saat menulis pesan error:

• Jangan berasumsi bahwa pengguna adalah pengguna ahli API Anda. Pengguna dapat berupa developer klien, staf operasional, staf IT, atau pengguna akhir aplikasi.
• Jangan berasumsi bahwa pengguna mengetahui apa pun tentang implementasi layanan Anda atau telah memahami konteks error (seperti analisis log).
• Jika memungkinkan, pesan error harus dibuat sedemikian rupa sehingga pengguna teknis (tetapi tidak selalu developer API Anda) dapat merespons error dan memperbaikinya.
• Jaga agar pesan error tetap singkat. Jika diperlukan, berikan link agar pembaca yang bingung dapat mengajukan pertanyaan, memberikan masukan, atau memperoleh informasi lebih lanjut yang tidak cukup dalam pesan error. Jika tidak, gunakan kolom detail untuk memperluas.

Peringatan: Pesan error bukan bagian dari platform API. Ketentuan ini dapat berubah tanpa pemberitahuan. Kode aplikasi tidak boleh memiliki dependensi kuat pada pesan error.

Detail Error

Google API menentukan kumpulan payload error standar untuk detail error, yang dapat Anda temukan di google/rpc/error_details.proto. Hal ini mencakup kebutuhan paling umum untuk error API, seperti kegagalan kuota dan parameter tidak valid. Seperti kode error, developer harus menggunakan payload standar ini jika memungkinkan.

Jenis detail error tambahan hanya boleh diperkenalkan jika dapat membantu kode aplikasi menangani error. Jika informasi error hanya dapat ditangani oleh manusia, andalkan konten pesan error dan biarkan developer menanganinya secara manual, bukan memperkenalkan jenis detail error tambahan.

Berikut beberapa contoh payload error_details:

• ErrorInfo: Memberikan informasi error terstruktur yang stabil dan dapat diperluas.
• RetryInfo: Menjelaskan kapan klien dapat mencoba lagi permintaan yang gagal, dapat ditampilkan pada Code.UNAVAILABLE atau Code.ABORTED
• QuotaFailure: Menjelaskan cara gagalnya pemeriksaan kuota, dapat ditampilkan pada Code.RESOURCE_EXHAUSTED
• BadRequest: Menjelaskan pelanggaran dalam permintaan klien, dapat ditampilkan pada Code.INVALID_ARGUMENT

Info Error

ErrorInfo adalah jenis payload error khusus. Class ini memberikan informasi error yang stabil dan dapat diperluas yang dapat diandalkan oleh manusia dan aplikasi. Setiap ErrorInfo memiliki tiga informasi: domain error, alasan error, dan kumpulan metadata error, seperti contoh ini. Untuk informasi selengkapnya, lihat definisi ErrorInfo.

Untuk Google API, domain error utama adalah googleapis.com, dan alasan error yang sesuai ditentukan oleh enum google.api.ErrorReason. Untuk informasi selengkapnya, lihat definisi google.api.ErrorReason.

Pelokalan Error

Kolom message di google.rpc.Status untuk developer dan harus dalam bahasa Inggris.

Jika pesan error yang ditampilkan kepada pengguna diperlukan, gunakan google.rpc.LocalizedMessage sebagai kolom detail Anda. Meskipun kolom pesan di google.rpc.LocalizedMessage dapat dilokalkan, pastikan kolom pesan di google.rpc.Status dalam bahasa Inggris.

Secara default, layanan API harus menggunakan lokalitas pengguna yang diautentikasi atau header Accept-Language HTTP atau parameter language_code dalam permintaan untuk menentukan bahasa pelokalan.

Pemetaan Error

Google API dapat diakses di berbagai lingkungan pemrograman. Setiap lingkungan biasanya memiliki cara penanganan error-nya sendiri. Bagian berikut menjelaskan cara pemetaan model error di lingkungan yang biasa digunakan.

Pemetaan HTTP

Meskipun pesan proto3 memiliki encoding JSON native, Platform API Google menggunakan skema error yang berbeda untuk JSON HTTP API Google demi alasan kompatibilitas mundur.

Skema:

// This message defines the error schema for Google's JSON HTTP APIs.
message Error {
  // Deprecated. This message is only used by error format v1.
  message ErrorProto {}
  // This message has the same semantics as `google.rpc.Status`. It uses HTTP
  // status code instead of gRPC status code. It has extra fields `status` and
  // `errors` for backward compatibility with [Google API Client
  // Libraries](https://developers.google.com/api-client-library).
  message Status {
    // The HTTP status code that corresponds to `google.rpc.Status.code`.
    int32 code = 1;
    // This corresponds to `google.rpc.Status.message`.
    string message = 2;
    // Deprecated. This field is only used by error format v1.
    repeated ErrorProto errors = 3;
    // This is the enum version for `google.rpc.Status.code`.
    google.rpc.Code status = 4;
    // This corresponds to `google.rpc.Status.details`.
    repeated google.protobuf.Any details = 5;
  }
  // The actual error payload. The nested message structure is for backward
  // compatibility with [Google API Client
  // Libraries](https://developers.google.com/api-client-library). It also
  // makes the error more readable to developers.
  Status error = 1;
}

Contoh (link):

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": {
          "service": "translate.googleapis.com"
        }
      }
    ]
  }
}

Pemetaan gRPC

Protokol RPC yang berbeda memetakan model error secara berbeda. Untuk gRPC, model error didukung secara native oleh kode yang dihasilkan dan library runtime dalam setiap bahasa yang didukung. Anda dapat mengetahui selengkapnya di dokumentasi API gRPC. Misalnya, lihat io.grpc.Status gRPC Java.

Pemetaan Library Klien

Library klien Google dapat memilih untuk menampilkan error secara berbeda per bahasa agar konsisten dengan idiom yang ditetapkan. Misalnya, library google-cloud-go akan menampilkan error yang mengimplementasikan antarmuka yang sama dengan google.rpc.Status, sedangkan google-cloud-java akan memunculkan Pengecualian.

Menangani Error

Berikut adalah tabel yang berisi semua kode error gRPC yang ditentukan dalam google.rpc.Code dan deskripsi singkat penyebabnya. Untuk menangani error, Anda dapat memeriksa deskripsi untuk kode status yang ditampilkan dan mengubah panggilan sebagaimana mestinya.

HTTP	gRPC	Deskripsi
200	OK	Tidak ada error.
400	INVALID_ARGUMENT	Klien menentukan argumen yang tidak valid. Periksa pesan error dan detail error untuk mengetahui informasi selengkapnya.
400	FAILED_PRECONDITION	Permintaan tidak dapat dieksekusi dalam status sistem saat ini, seperti menghapus direktori yang tidak kosong.
400	OUT_OF_RANGE	Klien menentukan rentang yang tidak valid.
401	UNAUTHENTICATED	Permintaan tidak diautentikasi karena token OAuth tidak ada, tidak valid, atau sudah tidak berlaku.
403	PERMISSION_DENIED	Klien tidak memiliki izin yang memadai. Hal ini dapat terjadi karena token OAuth tidak memiliki cakupan yang tepat, klien tidak memiliki izin, atau API belum diaktifkan.
404	NOT_FOUND	Resource yang ditentukan tidak ditemukan.
409	ABORTED	Konflik serentak, seperti konflik baca-ubah-tulis.
409	ALREADY_EXISTS	Resource yang klien coba buat sudah ada.
429	RESOURCE_EXHAUSTED	Kuota resource telah habis atau mencapai pembatasan kapasitas. Klien akan mencari detail error google.rpc.QuotaFailure untuk informasi selengkapnya.
499	CANCELLED	Permintaan dibatalkan oleh klien.
500	DATA_LOSS	Kehilangan data atau kerusakan data yang tidak dapat dipulihkan. Klien harus melaporkan error tersebut kepada pengguna.
500	UNKNOWN	Terjadi error yang tidak diketahui pada server. Biasanya berupa bug server.
500	INTERNAL	Error server internal. Biasanya berupa bug server.
501	NOT_IMPLEMENTED	Metode API tidak diimplementasikan oleh server.
502	T/A	Terjadi error jaringan sebelum menjangkau server. Biasanya terjadi pemadaman atau kesalahan konfigurasi jaringan.
503	UNAVAILABLE	Layanan tidak tersedia. Biasanya server sedang tidak aktif.
504	DEADLINE_EXCEEDED	Batas waktu permintaan terlampaui. Hal ini hanya akan terjadi jika pemanggil menetapkan batas waktu yang lebih pendek daripada batas waktu default metode (yaitu, batas waktu yang diminta tidak cukup bagi server untuk memproses permintaan) dan permintaan tidak selesai dalam batas waktu tersebut.

Peringatan: Google API dapat memeriksa beberapa prasyarat untuk permintaan API secara serentak. Menampilkan satu kode error tidak berarti prakondisi lain terpenuhi. Kode aplikasi tidak boleh bergantung pada urutan pemeriksaan prakondisi.

Error Percobaan Ulang

Klien dapat mencoba kembali pada error 503 UNAVAILABLE dengan backoff eksponensial. Penundaan minimum harus 1 detik kecuali jika didokumentasikan sebaliknya. Pengulangan pengulangan default harus satu kali kecuali jika didokumentasikan sebaliknya.

Untuk error 429 RESOURCE_EXHAUSTED, klien dapat mencoba lagi pada level yang lebih tinggi dengan penundaan minimum 30 detik. Percobaan ulang tersebut hanya berguna untuk tugas latar belakang yang berjalan lama.

Untuk semua error lainnya, percobaan ulang mungkin tidak berlaku. Pertama-tama, pastikan permintaan Anda idempoten, dan lihat google.rpc.RetryInfo untuk panduan.

Penyebaran Error

Jika layanan API Anda bergantung pada layanan lain, sebaiknya jangan begitu saja menyebarkan error dari layanan tersebut kepada klien Anda. Saat menerjemahkan error, sebaiknya hal berikut:

• Sembunyikan detail penerapan dan informasi rahasia.
• Sesuaikan pihak yang bertanggung jawab atas error tersebut. Misalnya, server yang menerima error INVALID_ARGUMENT dari layanan lain harus menyebarkan INTERNAL ke pemanggilnya sendiri.

Mereproduksi Error

Jika tidak dapat mengatasi error melalui analisis log dan pemantauan, Anda harus mencoba mereproduksi error dengan pengujian yang sederhana dan dapat diulang. Anda dapat menggunakan pengujian ini untuk mengumpulkan lebih banyak informasi terkait pemecahan masalah, yang dapat Anda berikan saat menghubungi dukungan teknis.

Sebaiknya gunakan curl -v dan Parameter Sistem untuk mereproduksi error dengan Google API. Keduanya dapat mereproduksi hampir semua permintaan Google API, dan memberi Anda informasi debug panjang. Untuk informasi selengkapnya, lihat halaman dokumentasi masing-masing untuk API yang Anda panggil.

Menghasilkan Error

Jika Anda adalah developer server, Anda harus membuat error dengan informasi yang memadai untuk membantu developer klien memahami dan menyelesaikan masalah. Pada saat yang sama, Anda harus menyadari keamanan dan privasi data pengguna, dan menghindari pengungkapan informasi sensitif dalam pesan error dan detail error, karena error sering kali dicatat ke dalam log dan dapat diakses oleh orang lain. Misalnya, pesan error seperti "Client IP address is not on whitelist 128.0.0.0/8" akan menampilkan informasi tentang kebijakan sisi server, yang mungkin tidak dapat diakses oleh pengguna yang memiliki akses ke log.

Untuk membuat error yang tepat, Anda harus memahami google.rpc.Code terlebih dahulu agar memilih kode error yang paling sesuai untuk setiap kondisi error. Aplikasi server dapat memeriksa beberapa kondisi error secara paralel, dan menampilkan kondisi pertama.

Tabel berikut mencantumkan setiap kode error dan contoh pesan error yang baik.

HTTP	gRPC	Contoh Pesan Error
400	INVALID_ARGUMENT	Kolom permintaan x.y.z adalah xxx, diharapkan salah satu dari [yyy, zzz].
400	FAILED_PRECONDITION	Resource xxx merupakan direktori yang tidak kosong, sehingga tidak dapat dihapus.
400	OUT_OF_RANGE	Parameter 'age' di luar rentang [0, 125].
401	UNAUTHENTICATED	Kredensial autentikasi tidak valid.
403	PERMISSION_DENIED	Izin 'xxx' ditolak untuk resource 'yyy'.
404	NOT_FOUND	Resource 'xxx' tidak ditemukan.
409	ABORTED	Tidak dapat memperoleh kunci pada resource 'xxx'.
409	ALREADY_EXISTS	Resource 'xxx' sudah ada.
429	RESOURCE_EXHAUSTED	Batas kuota 'xxx' terlampaui.
499	CANCELLED	Permintaan dibatalkan oleh klien.
500	DATA_LOSS	Lihat catatan.
500	UNKNOWN	Lihat catatan.
500	INTERNAL	Lihat catatan.
501	NOT_IMPLEMENTED	Metode 'xxx' tidak diterapkan.
503	UNAVAILABLE	Lihat catatan.
504	DEADLINE_EXCEEDED	Lihat catatan.

Catatan: Karena klien tidak dapat memperbaiki error server, membuat detail error tambahan tidak berguna. Untuk menghindari kebocoran informasi sensitif dalam kondisi error, sebaiknya jangan buat pesan error apa pun dan hanya buat detail error google.rpc.DebugInfo. DebugInfo dirancang khusus hanya untuk logging sisi server, dan tidak boleh dikirim ke klien.

Payload Error

Paket google.rpc menentukan kumpulan payload error standar, yang lebih disukai untuk payload error kustom. Tabel berikut mencantumkan setiap kode error dan payload error standar yang cocok, jika ada. Sebaiknya aplikasi tingkat lanjut mencari payload error ini di google.rpc.Status saat menangani error.

HTTP	gRPC	Detail Error yang Direkomendasikan
400	INVALID_ARGUMENT	google.rpc.BadRequest
400	FAILED_PRECONDITION	google.rpc.PreconditionFailure
400	OUT_OF_RANGE	google.rpc.BadRequest
401	UNAUTHENTICATED	google.rpc.ErrorInfo
403	PERMISSION_DENIED	google.rpc.ErrorInfo
404	NOT_FOUND	google.rpc.ResourceInfo
409	ABORTED	google.rpc.ErrorInfo
409	ALREADY_EXISTS	google.rpc.ResourceInfo
429	RESOURCE_EXHAUSTED	google.rpc.QuotaFailure
499	CANCELLED
500	DATA_LOSS	google.rpc.DebugInfo
500	UNKNOWN	google.rpc.DebugInfo
500	INTERNAL	google.rpc.DebugInfo
501	NOT_IMPLEMENTED
503	UNAVAILABLE	google.rpc.DebugInfo
504	DEADLINE_EXCEEDED	google.rpc.DebugInfo