Panduan Platform

Kesalahan & Batas Laju

Apa arti setiap kode status dan apa yang harus dilakukan.

Format kesalahan

Kesalahan dikembalikan sebagai JSON dalam format kesalahan OpenAI. Pesan menyatakan apa yang terjadi, code adalah pengidentifikasi stabil yang dapat dibaca mesin, dan id permintaan ditambahkan ke setiap pesan:

json

{
  "error": {
    "message": "Model \"gpt-5.5-typo\" is not offered here. Check the model name for typos, or switch to a model from our supported list. (request id: 20260705...)",
    "type": "new_api_error",
    "code": "model_not_found"
  }
}

Selalu sertakan id permintaan saat Anda menghubungi dukungan atau membuka tiket Discord. Itu memungkinkan kami menemukan permintaan Anda yang tepat di log.

Kode status sekilas

Kode status yang benar-benar akan Anda temui:

Kode	Arti	Yang harus dilakukan
`400`	Permintaan tidak valid: nilai parameter yang salah (misalnya max_tokens di bawah minimum model) atau prompt yang diblokir oleh moderasi konten.	Perbaiki permintaan. Mencoba lagi tanpa perubahan akan gagal lagi.
`401`	Masalah kunci: kunci API tidak ada, tidak valid, kedaluwarsa, atau dinonaktifkan.	Periksa header Authorization dan kunci Anda di halaman Token.
`402`	Batas pengeluaran kunci ini sendiri sudah habis.	Naikkan batas kunci atau buat kunci baru.
`403`	Akses ditolak: saldo akun kosong, model tidak diizinkan untuk kunci ini, atau IP Anda tidak ada di daftar izin kunci.	Isi ulang, atau periksa batasan model dan IP kunci.
`413`	Permintaan terlalu besar untuk batas uji coba gratis model ini.	Persingkat prompt atau beralih ke model berbayar.
`429`	Batas laju terpicu (lihat jenisnya di bawah).	Tunggu detik Retry-After, lalu coba lagi atau ganti model.
`500`	Ada yang gagal di pihak kami atau di penyedia upstream.	Coba lagi setelah menunggu sebentar; 500 yang terus-menerus layak dilaporkan.
`503`	Semua penyedia untuk model sedang sibuk, atau nama model tidak ada.	Baca pesannya: sibuk selesai dalam hitungan menit, salah ketik tidak.

503: sibuk vs model tidak dikenal

Dua situasi yang sangat berbeda berbagi status 503. Yang pertama adalah kemacetan sementara:

text

HTTP/1.1 503 Service Unavailable

{
  "error": {
    "message": "All providers for model \"kimi-k2.6:free\" are busy right now (they hit their rate limit). This is not a spelling error. Please try again in a little while, or switch to another model. (request id: 20260705...)",
    "type": "new_api_error",
    "code": "get_channel_failed"
  }
}

Kode get_channel_failed (semua penyedia sibuk) berarti setiap penyedia gratis untuk model tersebut sedang terkena batas laju sesaat. Ini pulih sendiri dalam hitungan menit: coba lagi atau ganti model. Kode model_not_found (tidak ditawarkan di sini) berarti nama model itu sendiri tidak dapat dikenali, dan mencoba lagi tidak akan pernah membantu. Periksa salah ketik atau cari nama saat ini di katalog.

Perlakukan 503 dengan get_channel_failed sebagai coba lagi/fallback dan 503 dengan model_not_found sebagai kesalahan keras di klien Anda.

Jenis-jenis batas laju

429 bisa berasal dari beberapa lapisan:

Batas model gratis kami: 1 permintaan per menit per model gratis per pengguna. Batas keadilan agar kumpulan bersama bertahan pada jam sibuk.
Batas penyedia upstream: penyedia di balik model gratis mencapai batasnya sendiri ("temporarily rate-limited upstream", yaitu sementara terkena batas laju di hulu).
Anggaran token harian pada beberapa kumpulan gratis; ini diatur ulang pada tengah malam UTC.
Batas token per menit yang terpicu pada prompt yang sangat besar.
Batas konkurensi per pengguna saat terlalu banyak permintaan berjalan paralel.

Model berbayar tidak memiliki batas laju yang diberlakukan oleh UnoRouter.

Batas model gratis secara rinci

Saat batas 1 per menit kami terpicu, Anda mendapatkan header batas laju standar, sehingga klien bisa mundur dengan tepat:

text

HTTP/1.1 429 Too Many Requests
Retry-After: 38
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1783198478

Retry-After bersifat dinamis: detik sebenarnya yang tersisa di jendela Anda, bukan 60 tetap. Pesan kesalahan juga menyebutkan kembaran berbayar dari model, yang tidak memiliki batas.

Batas ukuran uji coba

Beberapa model yang biasanya berbayar ditawarkan gratis dengan batas ukuran permintaan. Prompt yang terlalu besar mendapat 413 dengan pesan seperti: Request body too large for gpt-4.1 model. Max size: 8000 tokens.

Batas ini hanya berlaku untuk rute uji coba gratis; model berbayar menerima prompt panjang penuh.

Panduan coba lagi

Hormati Retry-After pada 429. Coba lagi 503 get_channel_failed setelah menunggu sebentar, atau beralih ke model lain. Jangan coba lagi kesalahan kelas 400, itu deterministik.

Permintaan yang gagal dan ditolak tidak ditagih: setiap penahanan awal pada saldo Anda dikembalikan saat permintaan bermasalah.