Error API

Halaman ini menyediakan 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 tidak ada dalam permintaan Anda. Periksa 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 dioptimalkan tanpa melalui autentikasi yang benar. Pastikan kunci API Anda ditetapkan dan memiliki akses yang tepat. Pastikan Anda melalui autentikasi yang benar untuk menggunakan model yang dioptimalkan.
404 NOT_FOUND Resource yang diminta tidak ditemukan. File gambar, audio, atau video yang direferensikan 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 kapasitas API (RPM, TPM, RPD, pengeluaran, dll.). Anda mengirim terlalu banyak permintaan, menggunakan terlalu banyak token, atau melampaui batas berbasis pengeluaran untuk histori penagihan dan paket akun Anda. Pastikan Anda berada dalam batas kapasitas model rate limits. Tunggu dan coba lagi setelah beberapa saat. Kurangi kapasitas atau ukuran permintaan Anda. Minta peningkatan batas kapasitas jika diperlukan.
499 CANCELLED Operasi dibatalkan, biasanya oleh pemanggil. Klien menutup koneksi sebelum API dapat menyelesaikan respons. Periksa apakah infrastruktur klien atau jaringan Anda menutup koneksi sebelum waktunya (misalnya, karena waktu tunggu 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 sedang kelebihan muatan atau tidak berfungsi untuk sementara. Layanan sedang kehabisan kapasitas untuk sementara. 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 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.
504 DEADLINE_EXCEEDED Layanan tidak dapat menyelesaikan pemrosesan dalam batas waktu. Perintah (atau konteks) Anda terlalu besar untuk diproses tepat waktu. Tetapkan 'waktu tunggu' 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 dalam SCREAMING_CASE.
details array Konteks error tambahan, seperti ErrorInfo atau LocalizedMessage.

Langkah berikutnya