Package google.rpc

Indeks

Kode

Kode error kanonis pada gRPC API.

Terkadang beberapa kode error dapat terjadi. Layanan seharusnya menampilkan kode error paling spesifik yang berlaku. Misalnya, lebih memilih menampilkan OUT_OF_RANGE daripada FAILED_PRECONDITION jika kedua kode berlaku. Demikian pula, untuk lebih memilih menampilkan NOT_FOUND atau ALREADY_EXISTS daripada FAILED_PRECONDITION.

Enum
OK

Bukan error: ditampilkan jika berhasil

Pemetaan HTTP: 200 OK
CANCELLED

Operasi dibatalkan, biasanya oleh pemanggil.

Pemetaan HTTP: 499 Client Closed Request
UNKNOWN

Error tidak diketahui. Misalnya, error ini dapat ditampilkan jika nilai Status yang diterima dari ruang alamat lain yang berada di ruang error yang tidak diketahui di ruang alamat ini. Selain itu, error yang dilaporkan oleh API yang tidak menampilkan informasi error yang mencukupi dapat dianggap sebagai error ini.

Pemetaan HTTP: Error Server Internal 500
INVALID_ARGUMENT

Klien menetapkan argumen yang tidak valid. Perhatikan bahwa ini berbeda dengan FAILED_PRECONDITION. INVALID_ARGUMENT menyatakan argumen yang bermasalah, terlepas dari keadaannya di dalam sistem (misalnya, nama file yang salah format).

Pemetaan HTTP: 400 Permintaan Tidak Valid
DEADLINE_EXCEEDED

Batas waktu berakhir sebelum operasi selesai. Untuk operasi yang mengubah keadaan sistem, error ini mungkin ditampilkan, bahkan jika, operasi tersebut telah selesai. Sebagai contoh, respons berhasil dari suatu server dapat tertunda selama waktu yang cukup lama hingga tenggat waktu berakhir.

Pemetaan HTTP: 504 Gateway Timeout
NOT_FOUND

Beberapa entity yang diminta (misalnya, file atau direktori) tidak ditemukan.

Catatan bagi developer server: apabila suatu permintaan ditolak pada seluruh kelas pengguna, seperti peluncuran bertahap, atau daftar yang diberi akses, NOT_FOUND dapat digunakan. Jika permintaan ditolak pada beberapa pengguna di dalam suatu kelas pengguna, seperti pada kontrol akses basis pengguna, maka, PERMISSION_DENIED harus digunakan.

Pemetaan HTTP: 404 Not Found
ALREADY_EXISTS

Entitas yang coba dibuat oleh klien (misalnya, file atau direktori) sudah ada.

Pemetaan HTTP: 409 Conflict
PERMISSION_DENIED

Pemanggil tidak memiliki izin untuk menjalankan operasi yang ditentukan. PERMISSION_DENIED tidak boleh digunakan untuk penolakan yang disebabkan oleh kehabisan beberapa resource (gunakan RESOURCE_EXHAUSTED untuk error tersebut). PERMISSION_DENIED tidak boleh digunakan apabila pemanggil tidak dapat diidentifikasi (gunakan UNAUTHENTICATED untuk error tersebut). Kode error ini tidak menyatakan bahwa suatu permintaan valid atau entitas yang diminta ada atau memenuhi prakondisi lainnya.

Pemetaan HTTP: 403 Forbidden
UNAUTHENTICATED

Permintaan tidak memiliki kredensial autentikasi operasi yang valid.

Pemetaan HTTP: 401 Tidak Sah
RESOURCE_EXHAUSTED

Beberapa resource telah habis, kemungkinan adalah kuota per pengguna, atau kemungkinan seluruh sistem file kehabisan ruang.

Pemetaan HTTP: 429 Too Many Requests
FAILED_PRECONDITION

Operasi tersebut ditolak karena sistem tidak dalam keadaan dibutuhkan untuk menjalankan operasi. Misalnya, direktori yang akan dihapus tidak kosong, operasi rmdir diterapkan pada non-direktori, dll.

Pelaksana layanan dapat menggunakan panduan berikut untuk menentukan manakah yang paling sesuai di antara FAILED_PRECONDITION, ABORTED, dan UNAVAILABLE: (a) Gunakan UNAVAILABLE apabila klien dapat mencoba kembali panggilan yang gagal sesegera mungkin. (b) Gunakan ABORTED apabila klien harus mencoba kembali pada tingkat yang lebih tinggi (misalnya, saat kegagalan test-and-set, yang menunjukkan bahwa klien harus memulai ulang urutan baca-ubah-tulis). (c) Gunakan FAILED_PRECONDITION jika klien tidak diizinkan untuk mencoba kembali hingga status sistem diperbaiki secara eksplisit. Misalnya, jika "rmdir" gagal karena direktori tidak kosong, FAILED_PRECONDITION akan ditampilkan karena klien tidak diizinkan untuk mencoba kembali kecuali jika file dihapus dari direktori.

Pemetaan HTTP: 400 Permintaan Tidak Valid
ABORTED

Operasi dibatalkan, umumnya karena masalah konkurensi seperti kegagalan pemeriksaan pengurut atau pembatalan transaksi.

Lihat panduan di atas untuk menentukan manakah yang sesuai antara FAILED_PRECONDITION, ABORTED, dan UNAVAILABLE.

Pemetaan HTTP: 409 Conflict
OUT_OF_RANGE

Upaya operasi dilakukan melampaui rentang yang valid. Mis., mencari tahu atau membaca melampaui akhir file.

Tidak seperti INVALID_ARGUMENT, error ini menunjukkan masalah yang dapat diperbaiki jika status sistem berubah. Misalnya, sistem file 32-bit akan menghasilkan INVALID_ARGUMENT jika diminta untuk membaca pada offset yang tidak berada dalam rentang [0,2^32-1], tetapi akan menghasilkan OUT_OF_RANGE jika diminta untuk membaca dari offset melewati ukuran file saat ini.

Terdapat sedikit tumpang-tindih antara FAILED_PRECONDITION dengan OUT_OF_RANGE. Sebaiknya gunakan OUT_OF_RANGE (error yang lebih spesifik) jika memang sesuai, sehingga pemanggil yang melakukan iterasi melalui ruang dapat dengan mudah mencari error OUT_OF_RANGE untuk dideteksi ketika selesai.

Pemetaan HTTP: 400 Permintaan Tidak Valid
UNIMPLEMENTED

Operasi tidak diterapkan atau tidak didukung/diaktifkan dalam layanan ini.

Pemetaan HTTP: 501 Not Implemented
INTERNAL

Error internal. Artinya beberapa invarian yang diperlukan oleh sistem pokok telah rusak. Kode error ini disediakan untuk error yang bersifat serius.

Pemetaan HTTP: Error Server Internal 500
UNAVAILABLE

Saat ini layanan tidak tersedia. Kemungkinan besar ini hanya kondisi sementara, yang dapat diperbaiki dengan mencoba kembali menggunakan backoff.

Lihat panduan di atas untuk menentukan manakah yang sesuai antara FAILED_PRECONDITION, ABORTED, dan UNAVAILABLE.

Pemetaan HTTP: 503 Layanan Tidak Tersedia
DATA_LOSS

Data hilang atau rusak yang tidak dapat dipulihkan.

Pemetaan HTTP: Error Server Internal 500

Status

Jenis Status menjelaskan model error logis yang cocok untuk berbagai lingkungan pemrograman, termasuk REST API dan RPC API. Ini digunakan oleh gRPC. Model error dirancang untuk menjadi:

  • Mudah untuk digunakan dan dimengerti oleh sebagian besar pengguna
  • Cukup fleksibel untuk memenuhi kebutuhan tak terduga

Ringkasan

Pesan Status berisi tiga bagian data: kode error, pesan error, dan detail error. Kode error harus berupa nilai enum dari google.rpc.Code, tetapi kode error dapat menerima kode error tambahan jika diperlukan. Pesan error harus berupa pesan berbahasa Inggris yang membantu developer memahami dan mengatasi error. Jika perlu terjemahan pesan error yang ditampilkan ke pengguna, letakkan pesan yang diterjemahkan dalam detail error atau terjemahkan di klien. Detail error opsional mungkin berisi informasi arbitrer tentang error tersebut. Ada satu set jenis detail error yang telah ditentukan dalam paket google.rpc yang dapat digunakan untuk kondisi error umum.

Pemetaan bahasa

Pesan Status merupakan representasi logis dari model error, tetapi pesan tersebut belum tentu merupakan format wire yang sebenarnya. Saat pesan Status ditampilkan di library klien dan protokol wire yang berbeda, maka pesan tersebut dapat dipetakan secara berbeda. Sebagai contoh, kemungkinan akan dipetakan ke beberapa pengecualian di Java, tetapi lebih mungkin dipetakan ke beberapa kode error dalam C.

Penggunaan lain

Model error dan pesan Status dapat digunakan dalam berbagai lingkungan, baik dengan atau tanpa API, untuk memberikan pengalaman developer yang konsisten di berbagai lingkungan.

Contoh penggunaan model error ini termasuk:

  • Error sebagian. Jika suatu layanan perlu menampilkan error sebagian kepada klien, layanan tersebut dapat menyematkan Status dalam respons normal untuk menunjukkan error sebagian.

  • Error alur kerja. Alur kerja biasanya memiliki beberapa langkah. Setiap langkah mungkin memiliki pesan Status untuk pelaporan error.

  • Operasi batch Jika klien menggunakan permintaan batch dan respons batch, pesan Status harus digunakan secara langsung di dalam respons batch, satu untuk masing-masing sub-respons error.

  • Operasi asinkron Jika panggilan API menyematkan hasil operasi asinkron dalam responsnya, status operasi tersebut harus diwakili secara langsung menggunakan pesan Status.

  • Logging. Jika beberapa error API disimpan dalam log, Status pesan dapat digunakan secara langsung setelah penghapusan yang diperlukan untuk alasan keamanan/privasi.

Kolom
code

int32

Kode status, harus berupa nilai enum dari google.rpc.Code.

message

string

Pesan error yang ditampilkan ke developer dan seharusnya dalam bahasa Inggris. Setiap pesan error yang ditampilkan kepada pengguna harus dilokalkan dan dikirim di kolom google.rpc.Status.details, atau dilokalkan oleh klien.

details[]

Any

Daftar pesan yang membawa detail error. Ada seperangkat jenis pesan umum untuk digunakan API.