Package google.rpc

Indeks

BadRequest

Mendeskripsikan pelanggaran dalam permintaan klien. Jenis error ini berfokus pada aspek sintaksis permintaan.

Kolom
field_violations[]

FieldViolation

Mendeskripsikan semua pelanggaran dalam permintaan klien.

FieldViolation

Jenis pesan yang digunakan untuk mendeskripsikan satu kolom permintaan buruk.

Kolom
field

string

Jalur yang mengarah ke kolom di isi permintaan. Nilai akan berupa urutan ID yang dipisahkan titik yang mengidentifikasi kolom buffer protokol.

Pertimbangkan hal berikut:

message CreateContactRequest {
  message EmailAddress {
    enum Type {
      TYPE_UNSPECIFIED = 0;
      HOME = 1;
      WORK = 2;
    }

    optional string email = 1;
    repeated EmailType type = 2;
  }

  string full_name = 1;
  repeated EmailAddress email_addresses = 2;
}

Dalam contoh ini, di proto field dapat mengambil salah satu nilai berikut:

  • full_name untuk pelanggaran pada nilai full_name
  • email_addresses[1].email untuk pelanggaran di kolom email pada pesan email_addresses pertama
  • email_addresses[3].type[2] untuk pelanggaran pada nilai type kedua dalam pesan email_addresses ketiga.

Dalam JSON, nilai yang sama ditampilkan sebagai:

  • fullName untuk pelanggaran pada nilai fullName
  • emailAddresses[1].email untuk pelanggaran di kolom email pada pesan emailAddresses pertama
  • emailAddresses[3].type[2] untuk pelanggaran pada nilai type kedua dalam pesan emailAddresses ketiga.
description

string

Deskripsi alasan elemen permintaan tidak valid.
reason

string

Alasan error tingkat kolom. Ini adalah nilai konstanta yang mengidentifikasi penyebab langsung error tingkat kolom. Kolom ini harus mengidentifikasi jenis FieldViolation secara unik dalam cakupan google.rpc.ErrorInfo.domain. Nilai ini harus berisi maksimal 63 karakter dan cocok dengan ekspresi reguler [A-Z][A-Z0-9_]+[A-Z0-9], yang mewakili UPPER_SNAKE_CASE.
localized_message

LocalizedMessage

Menyediakan pesan error yang dilokalkan untuk error tingkat kolom yang aman untuk ditampilkan kepada konsumen API.

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 jika klien harus mencoba lagi 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. Perlu diketahui bahwa mencoba kembali operasi non-idempoten tidak selalu aman.

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

ErrorInfo

Menjelaskan penyebab error dengan detail terstruktur.

Contoh error saat menghubungi API "pubsub.googleapis.com" saat API tersebut tidak diaktifkan:

{ "reason": "API_DISABLED"
  "domain": "googleapis.com"
  "metadata": {
    "resource": "projects/123",
    "service": "pubsub.googleapis.com"
  }
}

Respons ini menunjukkan bahwa pubsub.googleapis.com API tidak diaktifkan.

Contoh error yang ditampilkan saat mencoba membuat instance Spanner di region yang kehabisan stok:

{ "reason": "STOCKOUT"
  "domain": "spanner.googleapis.com",
  "metadata": {
    "availableRegions": "us-central1,us-east2"
  }
}
Kolom
reason

string

Alasan error. Ini adalah nilai konstanta yang mengidentifikasi penyebab langsung error. Alasan error bersifat unik dalam domain error tertentu. Nilai ini harus berisi maksimal 63 karakter dan cocok dengan ekspresi reguler [A-Z][A-Z0-9_]+[A-Z0-9], yang mewakili UPPER_SNAKE_CASE.
domain

string

Pengelompokan logis yang mencakup "alasan". Domain error biasanya adalah nama layanan terdaftar dari alat atau produk yang menghasilkan error. Contoh: "pubsub.googleapis.com". Jika error dihasilkan oleh beberapa infrastruktur umum, domain error harus berupa nilai unik secara global yang mengidentifikasi infrastruktur tersebut. Untuk infrastruktur Google API, domain error adalah "googleapis.com".
metadata

map<string, string>

Detail terstruktur tambahan tentang error ini.

Kunci harus cocok dengan ekspresi reguler [a-z][a-zA-Z0-9-_]+, tetapi idealnya menggunakan lowerCamelCase. Selain itu, panjangnya tidak boleh lebih dari 64 karakter. Saat mengidentifikasi nilai saat ini dari batas yang terlampaui, satuan harus ada dalam kunci, bukan nilai. Misalnya, bukan {"instanceLimit": "100/request"}, harus ditampilkan sebagai {"instanceLimitPerRequest": "100"}, jika klien melampaui jumlah instance yang dapat dibuat dalam satu permintaan (batch).

Bantuan

Menyediakan link ke dokumentasi atau untuk melakukan tindakan di luar band.

Misalnya, jika pemeriksaan kuota gagal dengan error yang menunjukkan bahwa project yang memanggil belum mengaktifkan layanan yang diakses, hal ini dapat berisi URL yang mengarah langsung ke tempat yang tepat di konsol developer untuk mengaktifkan bit.

Kolom

LocalizedMessage

Memberikan pesan error yang dilokalkan dan aman untuk ditampilkan kepada pengguna yang dapat dilampirkan ke error RPC.

Kolom
locale

string

Lokalitas yang digunakan mengikuti spesifikasi yang ditentukan di https://www.rfc-editor.org/rfc/bcp/bcp47.txt. Contohnya adalah: "en-US", "fr-CH", "es-MX"
message

string

Pesan error yang dilokalkan dalam lokalitas di atas.

PreconditionFailure

Mendeskripsikan prasyarat yang gagal.

Misalnya, jika RPC gagal karena memerlukan Persyaratan Layanan untuk disetujui, RPC tersebut dapat mencantumkan pelanggaran persyaratan layanan dalam pesan PreconditionFailure.

Kolom
violations[]

Violation

Menjelaskan semua pelanggaran prasyarat.

Pelanggaran

Jenis pesan yang digunakan untuk mendeskripsikan kegagalan prasyarat tunggal.

Kolom
type

string

Jenis PreconditionFailure. Sebaiknya gunakan jenis enum khusus layanan untuk menentukan subjek pelanggaran prasyarat yang didukung. Misalnya, "TOS" untuk "pelanggaran Persyaratan Layanan".
subject

string

Subjek, relatif terhadap jenis, yang gagal. Misalnya, "google.com/cloud" relatif terhadap jenis "TOS" akan menunjukkan persyaratan layanan mana yang dirujuk.
description

string

Deskripsi tentang penyebab kegagalan prasyarat. Developer dapat menggunakan deskripsi ini untuk memahami cara memperbaiki kegagalan.

Misalnya: "Persyaratan layanan belum disetujui".

QuotaFailure

Menjelaskan penyebab kegagalan pemeriksaan kuota.

Misalnya, jika batas harian terlampaui untuk project yang melakukan panggilan, layanan dapat merespons dengan detail QuotaFailure yang berisi ID project dan deskripsi batas kuota yang terlampaui. Jika project yang memanggil belum mengaktifkan layanan di konsol developer, layanan dapat merespons dengan project ID dan menyetel service_disabled ke benar (true).

Lihat juga jenis RetryInfo dan Bantuan untuk mengetahui detail lainnya tentang penanganan kegagalan kuota.

Kolom
violations[]

Violation

Menjelaskan semua pelanggaran kuota.

Pelanggaran

Jenis pesan yang digunakan untuk mendeskripsikan satu pelanggaran kuota. Misalnya, kuota harian atau kuota kustom yang terlampaui.

Kolom
subject

string

Subjek yang menyebabkan pemeriksaan kuota gagal. Misalnya, "clientip:" atau "project:".
description

string

Deskripsi tentang alasan pemeriksaan kuota gagal. Klien dapat menggunakan deskripsi ini untuk mengetahui lebih lanjut konfigurasi kuota dalam dokumentasi publik layanan, atau menemukan batas kuota yang relevan untuk disesuaikan melalui konsol developer.

Misalnya: "Layanan dinonaktifkan" atau "Batas Harian untuk operasi baca terlampaui".
api_service

string

Layanan API tempat QuotaFailure.Violation berasal. Dalam beberapa kasus, masalah Kuota berasal dari Layanan API selain yang dipanggil. Dengan kata lain, dependensi Layanan API yang dipanggil dapat menjadi penyebab QuotaFailure, dan kolom ini akan memiliki nama layanan API dependensi.

Misalnya, jika API yang dipanggil adalah Kubernetes Engine API (container.googleapis.com), dan terjadi pelanggaran kuota di Kubernetes Engine API itu sendiri, kolom ini akan menjadi "container.googleapis.com". Di sisi lain, jika pelanggaran kuota terjadi saat Kubernetes Engine API membuat VM di Compute Engine API (compute.googleapis.com), kolom ini akan menjadi "compute.googleapis.com".
quota_metric

string

Metrik kuota yang dilanggar. Metrik kuota adalah penghitung bernama untuk mengukur penggunaan, seperti permintaan API atau CPU. Saat aktivitas terjadi di layanan, seperti alokasi Virtual Machine, satu atau beberapa metrik kuota mungkin terpengaruh.

Misalnya, "compute.googleapis.com/cpus_per_vm_family", "storage.googleapis.com/internet_egress_bandwidth".
quota_id

string

ID kuota yang dilanggar. Juga dikenal sebagai "nama batas", ini adalah ID unik kuota dalam konteks layanan API.

Misalnya, "CPUS-PER-VM-FAMILY-per-project-region".
quota_dimensions

map<string, string>

Dimensi kuota yang dilanggar. Setiap kuota non-global diterapkan pada serangkaian dimensi. Meskipun metrik kuota menentukan apa yang harus dihitung, dimensi menentukan aspek yang harus ditingkatkan oleh penghitung.

Misalnya, kuota "CPU per region per VM family" menerapkan batas pada metrik "compute.googleapis.com/cpus_per_vm_family" pada dimensi "region" dan "vm_family". Jika pelanggaran terjadi di region "us-central1" dan untuk family VM "n1", quota_dimensions akan menjadi,

{ "region": "us-central1", "vm_family": "n1", }

Jika kuota diterapkan secara global, quota_dimensions akan selalu kosong.
quota_value

int64

Nilai kuota yang diterapkan pada saat QuotaFailure.

Misalnya, jika nilai kuota yang diterapkan pada saat QuotaFailure pada jumlah CPU adalah "10", maka nilai kolom ini akan mencerminkan jumlah ini.
future_quota_value

int64

Nilai kuota baru yang diluncurkan pada saat terjadinya pelanggaran. Setelah peluncuran selesai, nilai ini akan diterapkan sebagai pengganti quota_value. Jika tidak ada peluncuran yang sedang berlangsung pada saat terjadinya pelanggaran, kolom ini tidak akan ditetapkan.

Misalnya, jika pada saat terjadinya pelanggaran, peluncuran sedang berlangsung yang mengubah kuota jumlah CPU dari 10 menjadi 20, maka 20 akan menjadi nilai kolom ini.

RequestInfo

Berisi metadata tentang permintaan yang dapat dilampirkan klien saat melaporkan bug atau memberikan bentuk masukan lainnya.

Kolom
request_id

string

String buram yang hanya boleh ditafsirkan oleh layanan yang membuatnya. Misalnya, ID ini dapat digunakan untuk mengidentifikasi permintaan di log layanan.
serving_data

string

Data apa pun yang digunakan untuk menayangkan permintaan ini. Misalnya, stack trace terenkripsi yang dapat dikirim kembali ke penyedia layanan untuk proses debug.

ResourceInfo

Menjelaskan resource yang sedang diakses.

Kolom
resource_type

string

Nama untuk jenis resource yang diakses, misalnya "tabel sql", "bucket cloud storage", "file", "Google Kalender"; atau URL jenis resource: misalnya "type.googleapis.com/google.pubsub.v1.Topic".
resource_name

string

Nama resource yang diakses. Misalnya, nama kalender bersama: "example.com_4fghdhgsrgh@group.calendar.google.com", jika error saat ini adalah google.rpc.Code.PERMISSION_DENIED.
owner

string

Pemilik resource (opsional). Misalnya, "user:" atau "project:".
description

string

Menjelaskan error yang terjadi saat mengakses resource ini. Misalnya, memperbarui project cloud mungkin memerlukan izin writer pada project konsol developer.

RetryInfo

Menjelaskan kapan klien dapat mencoba lagi permintaan yang gagal. Klien dapat mengabaikan rekomendasi di sini atau mencoba lagi saat informasi ini tidak ada dalam respons error.

Klien selalu disarankan untuk menggunakan backoff eksponensial saat mencoba lagi.

Klien harus menunggu hingga jangka waktu retry_delay telah berlalu sejak menerima respons error sebelum mencoba lagi. Jika mencoba ulang permintaan juga gagal, klien harus menggunakan skema backoff eksponensial untuk secara bertahap meningkatkan penundaan antara percobaan ulang berdasarkan retry_delay, hingga jumlah percobaan ulang maksimum tercapai atau batas penundaan percobaan ulang maksimum tercapai.

Kolom
retry_delay

Duration

Klien harus menunggu setidaknya selama ini di antara upaya percobaan ulang permintaan yang sama.

Status

Jenis Status menentukan model error logis yang cocok untuk berbagai lingkungan pemrograman, termasuk REST API dan RPC API. Jenis error ini digunakan oleh gRPC. Setiap pesan Status berisi tiga bagian data: kode error, pesan error, dan detail error.

Anda dapat mencari tahu lebih lanjut tentang model error ini dan cara penanganannya di Panduan Desain API.

Kolom
code

int32

Kode status yang 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.