Platform

Kesalahan

Error dikembalikan sebagai JSON dalam format endpoint yang Anda panggil, dengan pesan yang mudah dipahami dan, pada endpoint bergaya OpenAI, kode tetap untuk diproses program.

Format

Endpoint bergaya OpenAI

{
  "error": {
    "message": "This API key can't use `gpt-6-astra`. It's limited to gpt-6-sol. Change that at https://zurelay.com/app/keys.",
    "type": "permission_error",
    "param": "model",
    "code": "model_not_allowed"
  }
}

Pada /v1/messages, error yang sama dikembalikan dalam format Anthropic, yang tidak memiliki kode: gunakan status HTTP dan error.type: { "type": "error", "error": { "type": "...", "message": "..." } }. Setiap respons chat, gambar, dan video, baik error maupun bukan, memiliki header x-request-id.

Kode

Status	Kode	Tindakan
400	`invalid_request`	Perbaiki permintaan: message menjelaskan masalahnya dan param menunjukkan letaknya.
400	`unsupported_content`	Model ini tidak bisa membaca jenis file tersebut. Hapus file itu atau pilih model yang mendukungnya.
400	`invalid_url`	Tautan dalam permintaan gagal diunduh. message memuat status yang diterima dari tautan tersebut.
400	`invalid_image`	Gambar input tidak dapat digunakan (jenis, ukuran, atau tautan).
400	`image_not_generated`	Model menolak prompt. Tidak dikenakan biaya.
400	`context_length_exceeded`	Menurut model, percakapan ini terlalu panjang. Persingkat atau pilih model dengan konteks lebih panjang.
400	`max_tokens_reached`	Jawaban non-streaming /v1/messages mencapai max_tokens Anda di tengah pemanggilan tool, sehingga pesannya tidak utuh. Bagian yang sudah dihasilkan tetap dikenakan biaya. Kirim ulang dengan max_tokens yang lebih tinggi.
401	`missing_api_key`	Kirim kunci melalui Authorization atau x-api-key.
401	`invalid_api_key`	Kunci salah atau sudah dicabut.
401	`expired_api_key`	Buat kunci baru.
402	`insufficient_quota`	Saldo, setelah dikurangi dana yang dicadangkan untuk permintaan yang sedang berjalan, tidak cukup untuk permintaan ini, atau habis saat jawaban masih dibuat. Tambah saldo di Penagihan, atau minta output lebih sedikit dengan menurunkan max_tokens. Jika isi ulang otomatis sudah dimulai, message akan menyebutkannya: coba lagi beberapa detik kemudian.
402	`key_budget_exceeded`	Permintaan ini bisa membuat penggunaan kunci melampaui anggaran bulanannya, termasuk permintaan yang sedang berjalan, atau anggaran sudah tercapai saat permintaan diproses. Naikkan anggaran, atau tunggu bulan depan.
402	`key_daily_budget_exceeded`	Hal yang sama berlaku untuk anggaran harian kunci. Naikkan anggaran, atau tunggu tengah malam UTC.
403	`model_not_allowed`	Kunci ini tidak diizinkan menggunakan model ini.
403	`ip_not_allowed`	Kunci ini hanya bisa digunakan dari alamat lain.
404	`model_not_found`	Periksa ID model di halaman model.
404	`unknown_url`	Endpoint tidak ditemukan. Periksa path dan URL dasar.
404	`video_not_found`	Tidak ada video dengan ID tersebut di ruang kerja ini.
404	`image_not_found`	Tidak ada permintaan gambar dengan ID tersebut di ruang kerja ini (GET /v1/images/{id}, untuk permintaan yang dibuat dengan callback_url).
409	`video_not_ready`	Video belum selesai: periksa secara berkala hingga status menjadi completed.
409	`video_failed`	Video gagal dibuat, jadi tidak ada yang bisa diunduh. error menjelaskan penyebabnya.
410	`video_expired`	Video telah dihapus, baik dari Pustaka maupun setelah 30 hari.
413	`too_large`	Permintaan atau file melebihi batas. Kirim file besar sebagai tautan.
429	`rate_limit_exceeded`	Tunggu selama jumlah detik di retry-after, lalu coba lagi.
429	`concurrency_limit_exceeded`	Ruang kerja ini sudah menjalankan 32 permintaan sekaligus. Coba lagi setelah menunggu selama jumlah detik di retry-after, saat salah satunya sudah selesai.
500	`server_error`	Terjadi kesalahan di pihak kami. Coba lagi.
502	`stream_interrupted`	Dikirim sebagai event terakhir dari stream yang terputus. Bagian yang dikirim sebelum terputus dikenakan biaya, setelahnya tidak; coba lagi.
503	`model_unavailable`	Model sedang tidak tersedia. Coba lagi setelah menunggu selama jumlah detik di retry-after, atau aktifkan perutean cerdas. Jika tidak ada retry-after dan x-should-retry: false, model tersedia tetapi selalu mengembalikan pesan kesalahan untuk permintaan ini: jangan kirim ulang tanpa perubahan.
503	`server_restarting`	Zurelay sedang memulai ulang mesin yang menangani permintaan Anda. Segera coba lagi: mesin lain akan menanganinya. Tidak dikenakan biaya, kecuali stream sudah dimulai: dalam hal itu, bagian yang Anda terima dikenakan biaya, sama seperti stream yang terputus.
503	`storage_unavailable`	Gambar berhasil dibuat tetapi tidak dapat dikirim. Tidak dikenakan biaya; coba lagi.
503	`service_unavailable`	Ada gangguan singkat di pihak kami. Coba lagi.

Mencoba ulang

Coba ulang 429 dan 503, dengan menunggu selama jumlah detik di header retry-after (atau menambah jeda secara eksponensial), kecuali respons menyatakan x-should-retry: false.
Jangan coba ulang error 4xx lainnya tanpa perubahan: hasilnya akan tetap gagal dengan cara yang sama.
Permintaan yang gagal tidak dikenakan biaya, jadi mencoba ulang tidak menambah biaya sampai ada yang berhasil. Stream yang terputus di tengah dikenakan biaya untuk bagian yang sudah dikirim, dan kasus langka 503 dengan x-should-retry: false dikenakan biaya untuk inputnya (lihat Penagihan).
SDK resmi OpenAI dan Anthropic sudah otomatis mencoba ulang error yang memang perlu dicoba ulang.

Error di tengah stream

Error dari model tentang permintaan Anda sendiri (parameter yang tidak didukung, prompt yang terlalu panjang) diteruskan dengan pesan dan kode asli dari model, sebagai 400 atau 422.

Error di tengah stream

Setelah stream dimulai, kegagalan tidak bisa lagi disampaikan sebagai status HTTP. Sebagai gantinya, Anda menerima event error terakhir (dalam format endpoint), lalu stream berakhir. Anda dikenakan biaya untuk input dan output yang sudah diterima sebelum error, bukan setelahnya. Ini jarang terjadi: sebagian besar masalah terdeteksi dan dicoba ulang sebelum token pertama.

Event sejenis juga mengakhiri stream jika saldo atau anggaran kunci habis di tengah proses, dengan insufficient_quota, key_budget_exceeded atau key_daily_budget_exceeded. Permintaan non-streaming yang kehabisan saldo atau anggaran di tengah proses mengembalikan bagian yang sudah ditulis, terpotong seperti jawaban yang mencapai max_tokens (finish_reason: "length", atau stop_reason: "max_tokens" pada /v1/messages), dengan header x-zurelay-stopped yang mencantumkan kodenya.

Ada pertanyaan, atau ada yang kurang? Tanyakan kepada tim dukungan kami dan kami akan menjawab lewat email, biasanya dalam satu menit.