Kode Error & Penanganannya

Atasi kegagalan request CometAPI dengan panduan terverifikasi untuk error 400, 401, dan path, serta penanganan praktis untuk kegagalan 403, 429, dan kelas timeout.

Penanganan error CometAPI paling mudah dilakukan saat Anda memisahkan masalah request, masalah auth, dan masalah platform yang bisa di-retry. Halaman ini adalah panduan error CometAPI yang kanonis dan berfokus pada hal-hal yang bisa Anda verifikasi dari sisi klien terlebih dahulu.

Panduan ini didasarkan pada pengecekan langsung terhadap API CometAPI saat ini. Kami memverifikasi 400, 401, dan kegagalan path/base URL secara langsung. Kami tidak mereproduksi 413, 429, 500, 503, 504, atau 524 dalam pengujian terbatas, sehingga panduan untuk status tersebut sengaja dibuat konservatif.

​

Triase Cepat

Status	Apa artinya biasanya	Retry?	Tindakan pertama
400	Validasi request gagal sebelum request berhasil dirutekan.	Tidak	Validasi model, messages, bentuk JSON, dan tipe field.
401	API key tidak ada, malformed, atau tidak valid.	Tidak	Periksa Authorization: Bearer <COMETAPI_KEY>.
403	Akses diblokir atau request saat ini tidak diizinkan.	Biasanya tidak	Coba lagi dengan request yang sudah dipastikan benar dan hapus dulu field yang spesifik ke model.
Path mistake	Base URL salah atau path endpoint salah. Pada Comet ini bisa muncul sebagai redirect 301 atau HTML, bukan JSON 404 yang bersih.	Tidak	Gunakan https://api.cometapi.com/v1 persis dan nonaktifkan auto-follow redirects saat debugging.
429	Rate limiting atau saturasi sementara.	Ya	Gunakan exponential backoff dengan jitter.
500, 503, 504, 524	Kegagalan platform atau kelas timeout.	Ya	Retry dengan backoff dan simpan request id.

​

Error Envelope

Envelope error JSON saat ini yang dikembalikan oleh CometAPI terlihat seperti ini:

{
	"error": {
		"code": "",
		"message": "...",
		"type": "comet_api_error"
	}
}

Banyak pesan error langsung juga menyertakan request id di dalam error.message. Simpan nilai tersebut saat Anda membutuhkan dukungan.

​

400 Bad Request

Yang kami amati dari API langsung saat model dihilangkan:

{
	"error": {
		"code": "",
		"message": "model name is required (request id: ...)",
		"type": "comet_api_error"
	}
}

Dalam praktiknya, 400 biasanya berarti body request gagal divalidasi sebelum platform dapat merutekannya ke penyedia model.

Penyebab umum:

• Field wajib seperti model atau messages tidak ada
• Bentuk JSON tidak valid
• Mengirim field dengan tipe yang salah
• Menggunakan kembali parameter spesifik penyedia yang tidak diterima oleh endpoint yang dipilih

Yang harus dilakukan:

1. Mulai dari request minimal yang sudah dipastikan benar.
2. Tambahkan kembali field opsional satu per satu.
3. Bandingkan body request dengan skema endpoint di referensi API.

Contoh minimal yang sudah dipastikan benar:

{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}

Ganti your-model-id dengan model ID saat ini dari halaman Models CometAPI.

​

401 Invalid Token

Yang kami amati dari API langsung dengan key yang tidak valid:

{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}

Yang perlu diperiksa:

1. Header harus persis Authorization: Bearer <COMETAPI_KEY>.
2. Pastikan aplikasi Anda tidak memuat key lama dari .env, riwayat shell, atau secret store yang sudah di-deploy.
3. Jika satu key gagal dan key lain berhasil pada request yang sama, anggap ini sebagai masalah token, bukan masalah endpoint.

​

403 Forbidden

Kami tidak mereproduksi 403 yang stabil dalam pengujian terbatas, jadi hindari menganggap satu template pesan lama sebagai keseluruhan ceritanya.

Pada dokumentasi Comet saat ini, 403 paling sering dibahas sebagai salah satu situasi berikut:

• Permintaan diblokir oleh aturan sisi platform seperti pemfilteran WAF
• token atau route tidak diizinkan menggunakan model atau bentuk permintaan yang diminta
• Model yang dipilih menolak salah satu parameter lanjutan yang Anda kirimkan

Yang perlu dilakukan terlebih dahulu:

1. Coba lagi dengan permintaan teks yang sangat sederhana terhadap model yang diketahui berfungsi baik.
2. Hapus field lanjutan dan parameter khusus provider, lalu tambahkan kembali secara bertahap.
3. Jika respons menyertakan request id, simpan itu sebelum menghubungi dukungan.

Jika pesan menyebutkan istilah internal seperti group atau channel, anggap itu sebagai detail routing, bukan hal pertama yang perlu didiagnosis dari sisi klien. Perbaikan praktisnya tetap memvalidasi token, model, dan bentuk permintaan terlebih dahulu.

​

Base URL Salah Atau Path Salah

Ini adalah area di mana halaman lama paling tidak akurat.

Dalam pemeriksaan langsung terhadap endpoint Comet saat ini:

• Mengirim POST ke https://api.cometapi.com/chat/completions mengembalikan redirect 301 ke https://www.cometapi.com/chat/completions
• Mengirim POST ke route API palsu seperti https://api.cometapi.com/v1/not-a-real-endpoint juga mengembalikan redirect 301 ke https://www.cometapi.com/v1/not-a-real-endpoint

Itu berarti kesalahan path dapat muncul sebagai:

• Redirect
• Respons HTML non-JSON jika klien Anda mengikuti redirect
• Error parsing di dalam SDK Anda
• Permintaan yang tidak pernah mencapai lapisan API dengan benar

Gunakan base URL ini persis seperti berikut:

https://api.cometapi.com/v1

Pemeriksaan yang direkomendasikan:

1. Pastikan base URL menyertakan /v1.
2. Pastikan path endpoint sama persis dengan dokumentasi.
3. Nonaktifkan mengikuti redirect otomatis saat men-debug masalah path.

​

413 Request Entity Too Large

Kami tidak mereproduksi 413 dalam pengujian terbatas, bahkan dengan request body JSON 8 MiB yang terlalu besar, jadi penjelasan lama bahwa prompt terlalu panjang terlalu sempit.

Jika Anda memang melihat 413, perlakukan itu pertama-tama sebagai masalah ukuran permintaan. Penyebab umum yang perlu dicurigai adalah:

• Payload base64 berukuran besar
• Gambar atau audio berukuran terlalu besar yang disematkan secara inline
• Body multipart atau JSON yang sangat besar

Yang perlu dilakukan:

1. Kurangi atau kompres konten yang dilampirkan.
2. Pecah pekerjaan besar menjadi permintaan yang lebih kecil.
3. Jangan berasumsi bahwa panjang teks biasa adalah satu-satunya penyebab.

​

429 Too Many Requests

Kami tidak mereproduksi 429 selama pengujian konkurensi terbatas terhadap 24 permintaan paralel GET /v1/models, jadi ambang pastinya jelas bergantung pada route, model, dan kondisi platform saat ini.

Perlakukan 429 sebagai sesuatu yang bisa dicoba ulang:

1. Gunakan exponential backoff dengan jitter.
2. Kurangi konkurensi burst.
3. Tetap aktifkan logging permintaan agar Anda dapat melihat route dan model mana yang lebih dulu mencapai saturasi.

Untuk pola retry yang dapat digunakan kembali, lihat contoh backoff di Chat Completions.

​

500, 503, 504, Dan 524

Kami tidak mereproduksi status-status ini dalam pengujian terbatas. Status tersebut seharusnya didokumentasikan sebagai kegagalan sisi server atau kelas timeout, bukan sebagai kesalahan pengguna.

Panduan praktis:

• 500: kegagalan internal platform atau sisi provider
• 503: route atau layanan provider sementara tidak tersedia
• 504 dan 524: kegagalan kelas timeout antara platform, edge, atau layanan provider

Yang perlu dilakukan:

1. Coba lagi dengan backoff.
2. Simpan request id, endpoint, model, dan timestamp.
3. Jika kegagalan yang sama berulang di beberapa kali retry, hubungi dukungan dengan konteks tersebut.

​

Sebelum Anda Menghubungi Dukungan

Kumpulkan detail berikut terlebih dahulu:

• Metode HTTP
• Path endpoint
• Nama model
• JSON request body yang sudah disanitasi (ini adalah item yang paling berguna untuk sebagian besar panggilan API)
• Parameter kueri jika request yang gagal menggunakannya
• Response body yang persis sama jika klien Anda merekamnya
• Status HTTP lengkap
• error.message yang persis sama
• request id apa pun
• Perkiraan stempel waktu
• Apakah request yang sama berfungsi dengan model lain atau token lain

Jika route yang gagal menerima unggahan file (pengeditan gambar, unggah audio, pembuatan video, dll.) alih-alih JSON body biasa, kirim payload yang setara dengan yang Anda submit:

• Nama field dan nilai teks yang Anda kirim bersama file
• Nama file, tipe file, dan perkiraan ukuran file
• Apakah file diunggah secara langsung, direferensikan melalui URL, atau disematkan sebagai base64

Cara tercepat untuk mereproduksi bug adalah payload request tersanitasi yang persis sama. Untuk sebagian besar panggilan API, itu berarti JSON request body mentah. Untuk route unggah file, itu berarti daftar field beserta metadata file.

Ini akan secara signifikan mempercepat waktu penanganan oleh tim dukungan.