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.

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.

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

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 BYOK.
byok_provider_not_found	Kamu tidak punya key BYOK untuk provider itu	Tambahkan key, atau perbaiki nama provider.
upstream_error	Provider menjawab dengan error klien yang tidak diklasifikasikan kenari	Periksa model dan field request, atau coba model lain.

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.
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.

402 Payment required

Kode	Kapan	Yang perlu dilakukan
insufficient_balance	Saldomu tidak cukup untuk request, batas biaya atau batas token sebuah key tercapai, 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. Untuk key yang dibatasi, pemilik membuat key pengganti dengan batas lebih tinggi lalu mencabut key yang sudah habis, karena batas sebuah key tidak bisa diubah. 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.

Lihat Cara penagihan.

403 Forbidden

Kode	Kapan	Yang perlu dilakukan
subscribers_only	Model hanya untuk akun dengan langganan aktif	Berlangganan, atau pilih model lain. Lihat Langganan.
byok_credential_unavailable	Kamu punya key BYOK untuk provider itu, tetapi tidak ada yang bisa melayani request saat ini karena dinonaktifkan atau dijeda	Aktifkan key, atau tunggu key yang dijeda pulih.
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, atau endpoint Key per tool	Pakai key dari akun itu sendiri.
restricted_key_not_allowed	Key yang dibatasi memanggil GET /v1/account/balance, GET /v1/account/quota, atau endpoint Key per tool	Pakai key tanpa pembatasan model, batas biaya, atau batas token. 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.

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	Lihat key kamu dengan GET /v1/account/keys dan pakai id dari sana. Lihat Key per tool.

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.

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

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