Penanganan error CometAPI paling mudah dilakukan ketika Anda memisahkan masalah bentuk request, masalah auth, kesalahan path, dan kegagalan platform yang bisa di-retry. Gunakan kombinasi status HTTP, error.code, dan error.message untuk memutuskan apakah request perlu diperbaiki atau di-retry.
Triase cepat
Error envelope
Banyak kegagalan CometAPI menggunakan body error seperti ini:
Beberapa respons membiarkan code kosong. Saat statusnya 500, perlakukan error.code dan error.message sebagai sinyal penentu.
400 Bad Request
400 biasanya berarti body request gagal validasi sebelum request dapat diproses secara normal.
Penyebab umum:
- Field wajib seperti
model tidak ada
- Bentuk JSON tidak valid
- Mengirim field dengan tipe yang salah
- Menggunakan kembali parameter khusus provider yang tidak diterima oleh endpoint yang dipilih
Mulailah dari request minimal yang sudah pasti benar, lalu tambahkan kembali field opsional satu per satu. Bandingkan payload dengan skema endpoint di referensi API.
Gunakan request minimal seperti ini:
Ganti your-model-id dengan model ID saat ini dari halaman Models CometAPI.
Jangan berasumsi bahwa setiap chat request yang salah format akan menghasilkan 400. Field chat wajib yang tidak ada seperti messages juga dapat muncul sebagai 500 dengan error.code: invalid_request.
500 Internal Server Error
Sebagian besar respons 500 menunjukkan kegagalan platform atau provider. Untuk Chat Completions, beberapa request yang salah format juga dapat muncul sebagai 500 sambil tetap membawa error.code: invalid_request.
Salah satu contohnya adalah request yang tidak menyertakan messages:
Jika respons 500 memiliki error.code: invalid_request, perlakukan itu sebagai masalah request:
- Perbaiki body request.
- Bandingkan payload dengan skema endpoint.
- Retry hanya setelah payload diperbaiki.
Jika respons 500 tidak menunjukkan request yang tidak valid, simpan request id dan gunakan backoff.
401 Invalid Token
Kegagalan token biasanya terlihat seperti ini:
Yang perlu diperiksa:
- Header harus persis
Authorization: Bearer $COMETAPI_KEY.
- Pastikan aplikasi Anda tidak memuat key lama dari
.env, riwayat shell, atau secret store yang sudah di-deploy.
- Jika satu key gagal dan key lain berfungsi pada request yang sama, anggap ini sebagai masalah token, bukan masalah endpoint.
403 Forbidden
403 paling sering merupakan salah satu dari situasi berikut:
- Request diblokir oleh aturan sisi platform seperti pemfilteran WAF
- Token atau route tidak diizinkan menggunakan model atau bentuk request yang diminta
- Model yang dipilih menolak salah satu parameter lanjutan yang Anda kirimkan
Apa yang harus dilakukan terlebih dahulu:
- Coba lagi dengan request teks yang sangat sederhana terhadap model yang diketahui berfungsi baik.
- Hapus field lanjutan dan parameter khusus provider, lalu tambahkan kembali secara bertahap.
- Jika respons menyertakan request id, simpan sebelum menghubungi dukungan.
Jika pesan menyebut istilah internal seperti group atau channel, anggap itu sebagai detail routing, bukan hal pertama yang harus didiagnosis dari sisi klien. Perbaikan praktisnya tetap memvalidasi token, model, dan bentuk request terlebih dahulu.
Base URL salah atau path salah
Di Comet, kesalahan path dapat muncul sebagai:
- Redirect
- Respons HTML non-JSON jika klien Anda mengikuti redirect
- Parsing error di dalam SDK Anda
- Request yang tidak pernah mencapai layer API dengan benar
Gunakan base URL ini persis:
Pemeriksaan yang direkomendasikan:
- Pastikan base URL menyertakan
/v1.
- Pastikan path endpoint sama persis dengan dokumentasi.
- Nonaktifkan mengikuti redirect otomatis saat men-debug masalah path.
413 Request Entity Too Large
Jika Anda melihat 413, anggap itu sebagai masalah ukuran request terlebih dahulu. Penyebab yang umum adalah:
- Payload base64 yang besar
- Gambar atau audio berukuran besar yang disematkan secara inline
- Body multipart atau JSON yang sangat besar
Yang harus dilakukan:
- Kurangi atau kompres konten yang dilampirkan.
- Bagi pekerjaan besar menjadi request yang lebih kecil.
- Jangan berasumsi bahwa panjang teks biasa adalah satu-satunya penyebab.
429 Too Many Requests
Anggap 429 dapat dicoba ulang:
- Gunakan exponential backoff dengan jitter.
- Kurangi konkurensi burst.
- Tetap aktifkan logging request 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.
503, 504, dan 524
Status-status ini adalah kegagalan sisi server atau kelas timeout.
Panduan praktis:
503: layanan route atau provider sementara tidak tersedia504 dan 524: kegagalan kelas timeout antara platform, edge, atau layanan provider
Yang harus dilakukan:
- Coba lagi dengan backoff.
- Simpan
request id, endpoint, model, dan timestamp.
- Jika kegagalan yang sama berulang di beberapa retry, hubungi dukungan dengan konteks tersebut.
Sebelum Anda menghubungi dukungan
Kumpulkan detail berikut terlebih dahulu:
- Metode HTTP
- Path endpoint
- Model ID
- JSON body request yang sudah disanitasi (ini adalah satu item yang paling berguna untuk sebagian besar panggilan API)
- Parameter query jika request yang gagal menggunakannya
- Body respons yang persis sama jika client Anda menangkapnya
- Status HTTP lengkap
error.message yang persis samarequest id apa pun- Stempel waktu perkiraan
- Apakah request yang sama berhasil dengan model lain atau token lain
Jika route yang gagal menerima unggahan file (pengeditan gambar, unggah audio, pembuatan video, dll.) alih-alih body JSON biasa, kirim payload yang setara dengan yang dikirim:
- Nama field dan nilai teks yang Anda kirim bersama file
- Nama file, jenis file, dan perkiraan ukuran file
- Apakah file diunggah secara langsung, direferensikan melalui URL, atau disematkan sebagai base64
Cara paling efektif untuk mereproduksi bug adalah payload request tersanitasi yang persis sama. Untuk sebagian besar panggilan API, itu berarti JSON body request mentah. Untuk route unggahan file, itu berarti daftar field ditambah metadata file.
