Error

kenari mengembalikan error dalam format yang sama dengan API yang kamu panggil. Tentukan penanganan error berdasarkan status HTTP dan code, atau error.type di Messages, bukan teks message. Sebagian besar pesan berbahasa Inggris dan beberapa berbahasa Indonesia, dan redaksinya bisa berubah.

Format error

Format OpenAI

Semua endpoint kecuali Messages mengembalikan body ini: Chat completions, Responses, Embeddings, Rerank, Moderasi, Gambar, audio, musik, video, OCR, pencarian web dan X, daftar model, dan kuota akun.

{
  "error": {
    "message": "free-model rate limit reached; slow down and retry",
    "type": "rate_limit_exceeded",
    "param": null,
    "code": "free_quota_rpm"
  }
}

Gunakan field code untuk menentukan penanganannya. type mengulang code pada sebagian besar error. Pengecualiannya adalah batas model gratis (type berisi rate_limit_exceeded), penolakan provider (type berisi invalid_request_error), shared_key_not_allowed, restricted_key_not_allowed, dan cli_login_key_required (type berisi permission_error), dan kegagalan internal pada GET /v1/account/balance, GET /v1/account/quota serta endpoint Pemakaian (type berisi api_error, code berisi internal_error). param selalu null, kecuali pada 400 dari endpoint Pemakaian, yang menyebut nama parameternya. API workspace mengisi type dari status HTTP, misalnya conflict_error untuk setiap 409.

Format Anthropic

Messages, termasuk count_tokens, mengembalikan error bergaya Anthropic. Tidak ada field code, jadi tentukan penanganan berdasarkan status HTTP dan error.type.

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "free-model rate limit reached; slow down and retry"
  }
}

error.type	Status HTTP
invalid_request_error	400, atau status milik provider untuk penolakan provider
not_found_error	400, atau status milik provider untuk penolakan provider
payment_required	402
permission_error	403
rate_limit_error	429
api_error	400, 500, dan 503

Status HTTP-nya sama dengan format OpenAI untuk kegagalan yang sama. Penolakan provider mempertahankan status milik provider, jadi kedua tipe ini tidak selalu 400. Lihat Penolakan provider. api_error datang dengan status 400 kalau provider menjawab dengan error klien yang tidak diklasifikasikan kenari.

Passthrough Claude Managed Agents juga memakai amplop ini, dengan code pada error yang dibuat kenari sendiri, seperti auth_failed. Error dari Anthropic diteruskan tanpa perubahan dan tidak punya code. Tentukan penanganan berdasarkan code kalau ada, dan berdasarkan error.type kalau tidak ada.

Error di dalam stream

Setelah stream dimulai, status HTTP sudah 200, jadi kegagalan datang sebagai event di dalam stream. Periksa setiap stream untuk event ini. Lihat Streaming.

Format API	Cara error datang
Chat completions	Chunk data: berisi objek error yang type-nya upstream_error
Messages	Event event: error dengan body Anthropic di atas
Responses	Event response.failed, dengan error di response.error

Di Chat completions dan Responses, code bernilai stream_interrupted kalau provider berhenti sebelum jawaban selesai. Event Messages punya error.type dan tidak punya code. Kirim ulang sebagai request baru. Penolakan provider di dalam stream memakai kode di bagian Penolakan provider.

Response teks biasa

Beberapa response berupa teks biasa, bukan JSON, karena request ditolak sebelum sampai ke API.

Status	Body	Penyebab
400	Failed to parse the request body as JSON...	Pada /v1/web/search dan /v1/ocr, body bukan JSON yang valid
401	missing authorization	Tidak ada header key
401	invalid key	Key tidak diawali kn-, tidak ada, sudah dicabut, sudah kedaluwarsa, atau milik akun yang ditangguhkan atau sedang dihapus
408	request body timed out	Body berhenti datang selama 30 detik, atau butuh lebih dari 5 menit untuk datang. Kirim ulang
413	request body too large	Body request lebih dari 32 MiB
415	Expected request with Content-Type: application/json	Pada /v1/web/search dan /v1/ocr, header Content-Type: application/json tidak ada
422	Failed to deserialize the JSON body...	Pada /v1/web/search dan /v1/ocr, field wajib tidak ada atau bertipe salah
429	too many requests, try again shortly	Satu IP klien mengirim terlalu banyak request pada API key dibagikan. Lihat Batas laju.
500	db error	kenari tidak bisa mencari key. Coba lagi.
503	server busy, try again shortly	kenari sedang menerima terlalu banyak body request besar sekaligus. Coba lagi sebentar lagi

Passthrough Claude Managed Agents menjawab dengan cara lain. Di sana, 401, 429 pada API key dibagikan, dan db error datang sebagai JSON dalam format Anthropic dengan kode auth_failed. Kegagalan lain di dalam kenari menghasilkan 500 dengan teks biasa internal error.

Untuk soal key, lihat Autentikasi & API key.

Kode error

400 Bad request

Kode	Kapan	Yang perlu dilakukan
bad_request	Body atau parameter tidak valid, atau pembatasan key menolak request (model tidak diizinkan, kemampuan tidak diberikan, rute pada key yang dibatasi). Dokumen terlampir dengan tipe tidak didukung, ukuran atau jumlah halaman di atas batas, atau panjang di atas konteks model juga ditolak di sini. Pada Embeddings, Rerank, Moderasi, dan System One, model yang tidak dikenal atau berjenis lain juga ditolak di sini, dan pesannya mendaftar id yang tersedia. Membuat key per tool ditolak di sini dengan key limit reached saat akunmu sudah mencapai batas key	Baca message, perbaiki request.
model_not_found	Pada Chat completions, Responses, dan Messages, id model atau nama rute tidak ada, atau tidak bisa kamu pakai. Pada Embeddings, Rerank, Moderasi, dan System One, modelnya terdaftar tetapi saat ini tidak ada provider yang melayaninya	Pilih id dari GET /v1/models, atau coba lagi nanti.
request_blocked	kenari menolak request berdasarkan kebijakan konten sebelum sampai ke provider	Ubah isi request.
byok_malformed_model_id	Id model byok/ tidak berbentuk byok/<provider>/<model>	Perbaiki id-nya. Lihat Provider.
byok_provider_not_found	Kamu tidak punya key atau koneksi untuk provider itu	Tambahkan key atau hubungkan langganannya, atau perbaiki nama provider.
invalid_path	Path di passthrough Claude Managed Agents memuat .., garis miring yang di-encode, atau backslash	Kirim path yang normal.
upstream_error	Provider menjawab dengan error klien yang tidak diklasifikasikan kenari	Periksa model dan field request, atau coba model lain.
invalid_request	Request API workspace punya body yang bukan JSON valid untuk route itu, nilai yang ditolak aturan workspace, id di path yang salah bentuk, atau header Idempotency-Key yang salah bentuk	Baca message, perbaiki request.
idempotency_key_required	Route API workspace yang membeli, mengubah, atau mengaktifkan lagi kursi, atau memindahkan saldo Pribadi, tidak membawa header Idempotency-Key	Kirim Idempotency-Key yang unik. Lihat API workspace.
pay_from_personal_not_supported	Request kursi di API workspace memakai pay_from selain workspace	Pindahkan dulu saldo Pribadi ke workspace, lalu beli kursinya. Lihat API workspace.

Penolakan provider

Kode-kode ini berarti provider model menolak request itu sendiri. Status HTTP-nya 400, atau 403, 404, 413, 415, 422, atau 429 milik provider, dan type berisi invalid_request_error.

Kode	Kapan	Yang perlu dilakukan
invalid_request_error	Provider menolak request karena cacat atau tidak didukung	Kirim request yang sama ke model lain. Kalau berhasil di sana, laporkan ke dukungan kenari.
context_length_exceeded	Prompt ditambah max_tokens melebihi context window model	Persingkat input, turunkan max_tokens, atau pakai model dengan konteks lebih panjang.
model_not_found	Provider sedang tidak melayani model itu	Coba lagi nanti atau pakai model lain.
content_policy_violation	Provider memblokir request berdasarkan kebijakan kontennya	Ubah isi request.
prefill_unsupported	Pesan terakhir berasal dari asisten, dan model tidak bisa melanjutkannya	Akhiri percakapan dengan pesan user atau tool.
reference_image_fetch_failed	Request video memuat gambar referensi yang tidak bisa diambil provider	Kirim setiap referensi sebagai URL https publik atau data URL.
upstream_rejected	Provider menolak request karena alasan yang tidak bisa diklasifikasikan kenari	Periksa id model dan field request.

kenari tidak mengulang request yang ditolak ke provider yang sama. Di dalam rute atau rantai BYOK, kenari bisa lanjut ke langkah berikutnya, karena penolakan satu provider belum membuktikan provider berikutnya akan menolak request yang sama, tetapi penolakan karena panjang konteks mengakhiri rantai. message ditulis oleh kenari dan tidak pernah memuat teks asli dari provider.

401 Unauthorized

Body-nya teks biasa. Lihat Response teks biasa. Periksa key-nya, atau buat key baru di dashboard.

Passthrough Claude Managed Agents menjawab dengan JSON, dengan kode ini:

Kode	Kapan	Yang perlu dilakukan
auth_failed	Key kn- tidak ada, salah, kedaluwarsa, atau dicabut	Periksa key-nya, atau buat key baru di dashboard.

402 Payment required

Kode	Kapan	Yang perlu dilakukan
insufficient_balance	Saldomu tidak cukup untuk request atau untuk biaya pencarian web, pengambilan halaman, atau pencarian X, atau pemilik API key dibagikan kehabisan dana	Top up, atau kirim prompt yang lebih pendek atau max_tokens yang lebih rendah. Pesannya menunjukkan saldo tersedia dan biaya terbesar yang mungkin untuk request ini, yaitu estimasi input ditambah max_tokens dengan tarif output. Dokumen yang dibaca dengan engine ocr atau /v1/ocr punya pesan sendiri: pesannya menyebut bahwa pembacaan dokumen ditagih per halaman dari saldo dan tidak dicakup paket, serta menunjukkan saldo yang tersedia dan saldo maksimum yang dicadangkan untuk pembacaan dokumen itu. Top up, atau kirim berkas tanpa engine ocr agar dibaca sebagai token input biasa.
payg_limit_reached	Kamu mencapai batas saldo PAYG yang kamu atur di pengaturan langganan. Cakupannya satu hari atau 30 hari berjalan	Naikkan atau hapus batasnya, atau tunggu sampai pemakaian lama keluar dari periode perhitungan. Kuota paket dan model gratis tidak terpengaruh.
key_spend_cap_reached	Batas biaya atau batas token API key ini sudah terpakai. Masalahnya bukan di saldo	Pemilik key menaikkan batas biaya atau mereset pemakaiannya di halaman Kunci API (key yang tidak dibagikan dan punya batas biaya), atau memakai key lain. Batas token dan batas key yang dibagikan tidak bisa diubah, jadi pemilik membuat key baru. Pemilik juga mendapat notifikasi saat batasnya pertama kali habis.
member_spend_cap_reached	Kamu anggota workspace tim dan sudah mencapai batas pengeluaran yang diatur Pemilik atau Admin untukmu. Batas ini menghitung pemakaianmu dari saldo workspace selama 30 hari berjalan: request PAYG, pemakaian di atas kuota kursimu, pencarian web, web fetch, pencarian X, gambar, dan video. Sebelum batas tercapai, kenari menurunkan max_tokens sampai sebesar yang masih bisa dibayar sisa batasmu, sama seperti saat saldo menipis	Minta Pemilik atau Admin workspace menaikkan atau menghapus batasmu di halaman Tim, atau tunggu sampai jendela 30 hari bergulir. Kuota kursimu dan model gratis tidak terpengaruh. Kamu juga mendapat notifikasi saat pertama kali mencapai batas dalam satu jendela.

Lihat Cara penagihan.

403 Forbidden

API workspace punya kode 403 sendiri. Kodenya terdaftar di sini, dan halaman itu menjelaskan masing-masing.

Kode	Kapan	Yang perlu dilakukan
subscribers_only	Model hanya untuk akun dengan langganan aktif	Berlangganan, atau pilih model lain. Lihat Langganan.
subscription_required	Request byok/chatgpt/... atau byok/grok/..., atau request ke passthrough Claude Managed Agents, dari akun tanpa Langganan aktif	Berlangganan. Lihat Provider.
byok_credential_unavailable	Kamu punya key atau koneksi untuk provider itu, tetapi tidak ada yang bisa melayani request saat ini karena dinonaktifkan, dijeda, atau keluar dari login	Aktifkan key, tunggu key yang dijeda pulih, atau hubungkan ulang langganannya.
byok_spend_capped_key	Key dengan batas biaya memanggil model byok/	Pakai key tanpa batas biaya. Batas token diperbolehkan.
shared_key_not_allowed	API key dibagikan memanggil GET /v1/account/balance, GET /v1/account/quota, endpoint Pemakaian, endpoint Key per tool, route API workspace, atau passthrough Claude Managed Agents	Pakai key dari akun itu sendiri.
restricted_key_not_allowed	Key yang dibatasi memanggil GET /v1/account/balance, GET /v1/account/quota, endpoint Key per tool, route API workspace, atau passthrough Claude Managed Agents, atau mengirim user_id ke endpoint Pemakaian	Pakai key tanpa pembatasan model, pembatasan kemampuan berbayar, batas biaya, atau batas token. Pemakaian key itu sendiri tetap bisa dibaca dari GET /v1/usage. Lihat Ringkasan akun.
cli_login_key_required	Key selain key dari kenari login memanggil endpoint Key per tool	Pakai key dari kenari login. Jalankan kenari login lagi kalau keymu lebih lama dari key per tool.
workspace_access_required	Route API workspace membutuhkan tingkat akses workspace yang lebih tinggi dari milik key, atau key itu adalah key yang disimpan kenari login atau key per tool	Buat key dengan tingkat yang dibutuhkan route itu. Lihat Autentikasi & API key.
teams_not_enabled	Route API workspace atau tool MCP kenari_workspace_* dipanggil sebelum workspace tim dibuka untuk akun itu	Jangan coba lagi. Request akan berhasil setelah workspace tim dibuka untuk akun itu.
not_a_team_workspace	Route API workspace selain GET /v1/workspace dipanggil dengan key di workspace Pribadi	Pakai key dari workspace tim.
permission_denied	Route API workspace untuk Pemilik atau Admin dipanggil dengan key yang dipegang Anggota, aturan workspace menolak perubahannya (misalnya mengeluarkan Pemilik), atau key yang dipegang Anggota mengirim user_id orang lain ke endpoint Pemakaian	Pakai key yang dipegang Pemilik atau Admin, atau ubah requestnya.
fund_cap_reached	Pemindahan POST /v1/workspace/fund-from-personal akan melewati batas harian key	Tunggu 24 jam berjalan berlalu, atau buat key dengan batas yang lebih tinggi. Pesannya menyebut sisa yang masih bisa dipindahkan.

404 Not found

Kode	Kapan	Yang perlu dilakukan
not_found	DELETE /v1/account/keys/{id} menerima id yang bukan key per tool aktif milik key yang memanggil, atau route API workspace menerima anggota, undangan, atau kursi yang tidak ada di workspace	Lihat key kamu dengan GET /v1/account/keys dan pakai id dari sana. Lihat Key per tool. Untuk API workspace, lihat daftar anggota, undangan, atau kursi dan pakai id dari daftar itu.
credential_not_found	Header x-kenari-credential di passthrough Claude Managed Agents bukan key Anthropic aktif milik akunmu	Pakai id key Anthropic yang aktif.

409 Conflict

Kode	Kapan	Yang perlu dilakukan
child_key_cap	Key login sudah memegang key per tool sebanyak yang diizinkan	Cabut satu dengan DELETE /v1/account/keys/{id}, lalu buat key baru. Lihat Key per tool.
anthropic_credential_required	Passthrough Claude Managed Agents tidak menemukan API key Anthropic aktif di akunmu	Tambahkan key Anthropic di tab Provider.
credit_limit_reached	Key Anthropic yang disebut di x-kenari-credential pada passthrough sudah menghabiskan kredit Claude-nya, dan berhenti otomatis menyala	Naikkan kredit, matikan berhenti otomatis, atau tunggu tanggal pembaruan. Lihat Provider.
credential_required	Passthrough menemukan dua key Anthropic aktif atau lebih dan tidak ada header x-kenari-credential	Sebut satu key di header, atau nonaktifkan yang lain.
conflict	Keadaan workspace menolak perubahan lewat API workspace, misalnya mengundang orang yang sudah menjadi anggota, workspace yang sudah mencapai batas anggota, atau menghapus kursi terakhir	Baca message, dan baca keadaannya dengan route GET.
idempotency_key_reused	Idempotency-Key di API workspace sudah dipakai untuk body atau route yang berbeda	Pakai Idempotency-Key baru untuk request baru.
request_in_progress	Request pertama di API workspace dengan Idempotency-Key ini masih berjalan	Baca keadaannya dengan route GET sebelum mencoba lagi.

413 Payload too large

Body request di atas 32 MiB ditolak dengan response teks biasa, bukan JSON. Lihat Response teks biasa. 413 dari provider model berupa error JSON. Lihat Penolakan provider. Kode di bawah ini berlaku untuk passthrough Claude Managed Agents, yang menerima body sampai 100 MB.

Kode	Kapan	Yang perlu dilakukan
request_too_large	Body request di passthrough Claude Managed Agents lebih dari 100 MB	Kirim body yang lebih kecil.

429 Too many requests

Setiap kode 429 dijelaskan, beserta perilaku Retry-After, di Batas laju.

Kode	Kapan
rate_limit_exceeded	Batas per menit akun, batas pembacaan pemakaian, batas pembuatan key per tool, lonjakan request gratis, anggaran token model gratis, atau proses musik bersamaan
free_quota_rpm	Batas per menit model gratis
free_quota_daily	Kuota harian model gratis, yang direset pukul 00:00 UTC
plan_limit_reached	Jendela kuota langganan habis, dan PAYG serta fallback gratis nonaktif
upstream_error	Provider membatasi laju request
passthrough_busy	Terlalu banyak request passthrough Claude Managed Agents yang sedang berjalan. Coba lagi sebentar lagi
rate_limited	Batas per key untuk perubahan lewat API workspace
pending_limit_reached	Workspace punya terlalu banyak undangan tertunda
daily_limit_reached	Workspace sudah mencapai batas undangan harian

500 Internal server error

Kode	Kapan	Yang perlu dilakukan
internal_error	Ada yang gagal secara tak terduga di kenari	Coba sekali lagi. Kalau terus terjadi, laporkan header request-id ke dukungan kenari.

503 Service unavailable

Kode	Kapan	Yang perlu dilakukan
upstream_error	Provider timeout, tidak terjangkau, atau gagal	Coba lagi dengan backoff.
all_providers_failed	Semua provider, atau semua langkah rute, gagal. Retry-After dikirim saat provider dijeda atau penuh	Coba lagi setelah Retry-After detik, atau pakai rute dengan langkah fallback. Lihat Routing & rute.
no_wire_for_modality	Saat ini tidak ada provider yang melayani jenis request ini untuk model itu, misalnya chat, gambar, edit, atau embedding	Coba lagi nanti, atau pakai model lain.

Nama provider

Pesan error tidak pernah menyebut provider di balik sebuah model. kenari menulis setiap pesan sendiri.

Request panjang

Request non-stream yang berjalan sekitar dua menit tanpa response bisa diputus oleh jaringan edge sebelum jawabannya sampai ke kamu. Untuk prompt panjang, misalnya di atas 100.000 token, max_tokens besar, atau model penalaran yang lambat, set "stream": true. Stream menjaga koneksi tetap terbuka selama model bekerja. Lihat Streaming.

Saat request non-stream masih berjalan setelah menunggu lama, kenari bisa menjaga koneksi tetap terbuka dengan mengirim spasi sebelum body JSON. Parser JSON mengabaikan spasi itu. Pada saat itu baris status sudah 200, jadi periksa body untuk objek error sebelum membaca jawabannya.

Menangani error

1. Di API berformat OpenAI, pakai status HTTP dan code. Di Messages, pakai status HTTP dan error.type. Anggap message sebagai teks untuk manusia.
2. Coba ulang 429 dengan rate_limit_exceeded, free_quota_rpm, atau upstream_error, serta 500 dan 503. Tunggu Retry-After kalau ada, dan pakai exponential backoff dengan jitter kalau tidak ada.
3. Jangan coba ulang error 4xx lain tanpa perubahan. Perbaiki dulu request, key, atau saldonya.
4. Untuk 402, top up atau ubah batas yang tercapai, lalu kirim request lagi.
5. Periksa stream untuk event error, dan jangan berasumsi setiap body error berupa JSON. Lihat Response teks biasa.
6. Catat header response request-id, dan sertakan saat menghubungi dukungan kenari.

Lihat juga

• Batas laju
• Autentikasi & API key
• Streaming
• Cara penagihan