Error & status
kenari mengembalikan error dalam format yang sama dengan API yang kamu panggil: gaya OpenAI untuk /v1/chat/completions, /v1/responses, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/music/generations, /v1/videos/generations, /v1/videos/extensions, dan /v1/models, sedangkan gaya Anthropic dipakai untuk /v1/messages. Status HTTP-nya identik di kedua jalur.
Format error OpenAI
Section titled “Format error OpenAI”{ "error": { "message": "...", "type": "<code>", "param": null, "code": "<code>" } }type dan code berisi kode error kenari yang sama, kecuali penolakan upstream: type selalu invalid_request_error dan code memuat alasan spesifik (context_length_exceeded, model_not_found, content_policy_violation, invalid_request_error, atau upstream_rejected).
Tabel error
Section titled “Tabel error”| HTTP | code | arti |
|---|---|---|
| 400 | bad_request | body request tidak valid |
| 400 | model_not_found | model atau nama rute tidak tersedia |
| 400 | upstream_error | provider upstream menolak request (status 4xx, kecuali 429) |
| 401 | (teks biasa) | key kn- hilang atau salah |
| 402 | insufficient_balance | saldo IDR habis untuk request berbayar, isi saldo dulu |
| 402 | payg_limit_reached | batas pengeluaran PAYG kamu tercapai, naikkan batas di Pengaturan atau tunggu jendela reset |
| 403 | subscribers_only | model khusus pelanggan langganan |
| 403 | shared_key_not_allowed | key yang dibagikan tidak boleh membaca kuota akun |
| 429 | rate_limit_exceeded | terlalu banyak request (batas RPM akun atau model gratis) |
| 429 | free_quota_daily | jatah harian model gratis habis, reset 00:00 UTC. Top up atau berlangganan untuk menaikkannya (header Retry-After akurat) |
| 429 | free_quota_rpm | batas RPM model gratis tercapai, tunggu beberapa detik (header Retry-After akurat) |
| 429 | plan_limit_reached | kuota jendela langganan habis, aktifkan PAYG atau tunggu reset |
| 429 | upstream_error | provider upstream membatasi laju request, tunggu lalu coba lagi |
| 4xx | invalid_request_error | upstream menolak request sebagai tidak valid (field/body salah) |
| 4xx | context_length_exceeded | request melebihi context window maksimum model |
| 4xx | content_policy_violation | upstream memblokir request karena content policy |
| 4xx | upstream_rejected | penolakan upstream yang alasannya tak dikenali (fallback) |
| 503 | upstream_error | satu provider upstream gagal (timeout / 5xx) |
| 503 | all_providers_failed | semua provider atau langkah rute gagal |
| 503 | no_wire_for_modality | tidak ada endpoint aktif yang melayani modality yang diminta (chat, image, edit, embedding) |
| 500 | internal_error | error gateway tak terduga |
Format error Anthropic
Section titled “Format error Anthropic”POST /v1/messages memakai format error gaya Anthropic:
{ "type": "error", "error": { "type": "<type>", "message": "..." } }error.type berisi invalid_request_error (400), not_found_error (400), payment_required (402), permission_error (403), rate_limit_error (429), dan api_error (500/503). Status HTTP-nya sama dengan tabel di atas.
Menangani error
Section titled “Menangani error”- 429/503 dengan header
Retry-After. Batas RPM model gratis, batas kuota harian model gratis, dan kegagalan 503 saat semua key provider sedang dijeda (cooling) menyertakanRetry-After(detik sampai jendela berikutnya). SDK resmi sudah membaca header ini dan mundur otomatis. Limit lain (burst akun, kuota langganan) tidak mengirimRetry-After, supaya tidak menyesatkan. - 402 insufficient_balance. Isi saldo via QRIS lalu ulangi. Lihat Penagihan & Rupiah.
- 503 all_providers_failed. Semua backend untuk model itu gagal. Biasanya sementara (header
Retry-Afterikut terkirim saat key provider sedang dijeda). Coba lagi, atau pakai Rute kenari dengan langkah cadangan. - Prompt sangat panjang (di atas 100 ribu token). Pakai
"stream": true: response non-stream yang berjalan lebih dari 100 detik tanpa data keluar bisa dipotong oleh edge network sebelum sampai ke kamu, sementara endpoint streaming mengirim baris keepalive berkala (komentar SSE yang diabaikan parser) selama prefill sehingga koneksinya tetap hidup walau belum ada token pertama. - Penolakan upstream (
invalid_request_error/context_length_exceeded/model_not_found/content_policy_violation/upstream_rejected). Penolakan dari upstream yang murni karena request salah (body cacat, context habis, model tak ada, atau content policy). Status 4xx aslinya dipertahankan bila termasuk {400, 403, 404, 413, 422, 429}. Selain itu jadi 400.codemenandai alasannya supaya SDK bisa bercabang tanpa membaca teks. Pesannya adalah teks tetap milik kenari, bukan body upstream. Untuk dispatch langsung ke satu provider (body diteruskan apa adanya), request tidak diulang di panggilan yang sama. Tapi di dalam rute berlapis atau chain kredensial BYOK, penolakan ini tidak final: kenari tetap lanjut mencoba backend atau kredensial berikutnya di chain, karena request ditulis ulang per backend sehingga satu penolakan tidak membuktikan backend lain akan menolak permintaan yang sama.