Error API

Halaman ini memberikan referensi untuk kode error backend yang ditampilkan oleh GenerateContent API, menjelaskan format respons error gRPC, dan memberikan langkah-langkah pemecahan masalah.

Kode error HTTP

Tabel berikut mencantumkan kode error backend umum, penjelasan penyebabnya, dan solusi yang direkomendasikan:

Kode HTTP Status Deskripsi Contoh Solusi
400 INVALID_ARGUMENT Isi permintaan salah format. Ada kesalahan ketik, atau kolom wajib diisi yang tidak ada dalam permintaan Anda. Lihat referensi API untuk mengetahui format permintaan, contoh, dan versi yang didukung. Menggunakan fitur dari versi API yang lebih baru dengan endpoint yang lebih lama dapat menyebabkan error.
400 FAILED_PRECONDITION Paket gratis Gemini API tidak tersedia di negara Anda. Aktifkan penagihan di project Anda di Google AI Studio. Anda membuat permintaan di wilayah yang tidak mendukung paket gratis, dan Anda belum mengaktifkan penagihan di project Anda di Google AI Studio. Untuk menggunakan Gemini API, Anda harus menyiapkan paket berbayar menggunakan Google AI Studio.
403 PERMISSION_DENIED Kunci API Anda tidak memiliki izin yang diperlukan. Anda menggunakan kunci API yang salah; Anda mencoba menggunakan model yang di-tune tanpa melalui autentikasi yang tepat. Pastikan kunci API Anda ditetapkan dan memiliki akses yang tepat. Selain itu, pastikan untuk melakukan autentikasi yang tepat untuk menggunakan model yang di-tuning.
404 NOT_FOUND Resource yang diminta tidak ditemukan. File gambar, audio, atau video yang dirujuk dalam permintaan Anda tidak ditemukan. Periksa apakah semua parameter dalam permintaan Anda valid untuk versi API Anda.
429 RESOURCE_EXHAUSTED Anda telah melampaui salah satu batas frekuensi API (RPM, TPM, RPD, pembelanjaan, dll.). Anda mengirim terlalu banyak permintaan, menggunakan terlalu banyak token, atau melampaui batas berbasis pembelanjaan untuk histori penagihan dan tingkat akun Anda. Pastikan Anda berada dalam batas kecepatan model. Tunggu dan coba lagi setelah beberapa saat. Kurangi frekuensi atau ukuran permintaan Anda. Minta peningkatan batas frekuensi panggilan jika diperlukan.
499 DIBATALKAN Operasi dibatalkan, biasanya oleh pemanggil. Klien menutup koneksi sebelum API dapat menyelesaikan respons. Periksa apakah klien atau infrastruktur jaringan Anda menutup koneksi sebelum waktunya (misalnya, karena waktu tunggu di sisi klien).
500 INTERNAL Terjadi error yang tidak terduga di pihak Google. Konteks input Anda terlalu panjang. Periksa halaman status Gemini API untuk mengetahui insiden yang sedang berlangsung. Kurangi konteks input Anda atau beralihlah sementara ke model lain (misalnya, dari Gemini 2.5 Pro ke Gemini 2.5 Flash) dan lihat apakah berhasil. Atau, tunggu sebentar dan coba lagi permintaan Anda. Jika masalah berlanjut setelah mencoba lagi, laporkan masalah tersebut menggunakan tombol Kirim masukan di Google AI Studio.
503 UNAVAILABLE Layanan mungkin mengalami kelebihan beban atau gangguan sementara. Layanan ini untuk sementara kehabisan kapasitas. Periksa halaman status Gemini API untuk mengetahui insiden yang sedang berlangsung. Beralihlah sementara ke model lain (misalnya, dari Gemini 2.5 Pro ke Gemini 2.5 Flash) dan lihat apakah model tersebut berfungsi. Atau, tunggu sebentar dan coba lagi permintaan Anda. Jika masalah berlanjut setelah mencoba lagi, laporkan masalah tersebut menggunakan tombol Kirim masukan di Google AI Studio.
504 DEADLINE_EXCEEDED Layanan tidak dapat menyelesaikan pemrosesan dalam batas waktu. Perintah (atau konteks) Anda terlalu besar untuk diproses tepat waktu. Tetapkan 'timeout' yang lebih besar dalam permintaan klien Anda untuk menghindari error ini.

Format respons error

Jika permintaan GenerateContent gagal, API akan menetapkan kode status HTTP (seperti 400 Bad Request, 403 Forbidden, atau 429 Too Many Requests) dan menampilkan isi respons JSON yang berisi detail status gRPC:

{
  "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": "generativelanguage.googleapis.com"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ]
  }
}
Kolom Jenis Deskripsi
code bilangan bulat Kode status HTTP.
message string Deskripsi error yang dapat dibaca manusia.
status string Kode status gRPC di SCREAMING_CASE.
details array Konteks error tambahan, seperti ErrorInfo atau LocalizedMessage.

Langkah berikutnya