Gemini 503 “The model is overloaded” (UNAVAILABLE) — retry yang berhasil dan kapan harus berhenti

“The model is overloaded” adalah satu-satunya error Gemini yang bukan tentang Anda: pool penyajian untuk model tersebut saat ini tidak memiliki kapasitas. Tidak ada pengaturan proyek yang dapat mencegahnya — yang dapat Anda kendalikan adalah seberapa baik Anda melewatinya dan fallback mana yang digunakan jika error tidak berlalu.

Error

respons (HTTP 503)

{
  "error": {
    "code": 503,
    "message": "The model is overloaded. Please try again later.",
    "status": "UNAVAILABLE"
  }
}

Ringkasan penyebab dan perbaikan

Penyebab	Perbaikan
Lonjakan permintaan pada pool penyajian model tersebut	Exponential backoff dengan jitter; lonjakan biasanya berlalu dalam hitungan detik hingga beberapa menit.
Varian model preview / eksperimental	Build -exp dan preview berjalan pada pool kecil dan lebih dahulu mengalami overload. Gunakan alias stabil untuk produksi.
Request berat pada jam sibuk	Context besar dan batas maksimum output lebih mungkin dihentikan saat beban tinggi — pangkas yang tidak diperlukan dan lakukan streaming terhadap respons.

Pastikan ini 503 UNAVAILABLE, bukan 429

429 RESOURCE_EXHAUSTED adalah kuota Anda; 503 UNAVAILABLE adalah kapasitas Google. Perbedaan ini menentukan semuanya setelahnya: error kuota memerlukan perubahan penagihan atau batas, sedangkan error kapasitas memerlukan retry dan fallback. Jangan men-debug pengaturan proyek untuk 503 — tidak ada yang dapat ditemukan di sana.

Retry dengan backoff — tetapi dengan anggaran

503 secara definisi dapat di-retry. Gunakan exponential backoff dengan jitter yang sama seperti untuk 429 mana pun (snippet dalam panduan Claude 429 kami dapat digunakan tanpa perubahan — snippet itu sudah me-retry status kelas 500), tetapi batasi total waktu tunggu sesuai kemampuan caller; overload yang bertahan lebih dari sekitar 5 percobaan selama satu menit tidak akan segera berlalu.

Saat retry habis: ganti model, bukan loop

Siapkan rantai fallback sebelum dibutuhkan: alias stabil jika Anda menggunakan build preview, gemini-2-5-flash jika 2.5 Pro yang mengalami masalah (atau sebaliknya), atau provider lain sepenuhnya untuk request yang tidak boleh gagal. Fallback mengubah outage menjadi penurunan kualitas.

Jika Anda melakukan panggilan melalui Kunavo

Mode kegagalan ini adalah alasan Kunavo melakukan retry di dalam request: ketika sebuah model memiliki lebih dari satu channel upstream yang dikonfigurasi, percobaan yang gagal dialihkan ke channel lain sebelum error terlihat oleh Anda — kegagalan upstream sementara menjadi keberhasilan yang lebih lambat, bukan 503 Anda. Request yang gagal tidak pernah ditagihkan, dan karena satu kunci mencakup Gemini, Claude, dan GPT, fallback lintas provider pada langkah 3 cukup dilakukan dengan mengubah string model, bukan integrasi kedua. Sedang mempertimbangkan model fallback? Tarif per token untuk seluruh keluarga Gemini, di samping harga daftar Google, tercantum di Daftar harga Gemini API.

Pertanyaan umum

Apakah permintaan yang menghasilkan 503 dikenai biaya?

Tidak — permintaan ditolak sebelum inferensi, jadi Google tidak menagihnya, dan di Kunavo permintaan yang gagal juga tidak pernah ditagih. Biaya 503 adalah latensi dan percobaan ulang, bukan token.

Berapa lama overload Gemini berlangsung?

Biasanya beberapa detik hingga beberapa menit; lonjakan saat peluncuran model baru dapat berlangsung lebih lama. Karena itu, kebijakan yang masuk akal adalah beberapa percobaan ulang dengan backoff, lalu model cadangan — bukan loop percobaan ulang tanpa batas.

Apakah peningkatan ke tingkat berbayar menghentikan 503?

Tidak. Tingkat berbayar meningkatkan kuota Anda (keluarga 429), tetapi 503 UNAVAILABLE adalah kapasitas layanan bersama — trafik gratis dan berbayar sama-sama mengalaminya saat pool penuh. Model cadangan adalah mitigasinya, bukan penagihan.

Panduan terkait

Detail semantik error lainnya tersedia di referensi error; mendapatkan kunci hanya perlu satu menit melalui pendaftaran dan panduan autentikasi.