> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Menangani kode error

> Gunakan panduan ini untuk mengklasifikasikan respons error CometAPI dan menerapkan langkah retry atau perbaikan untuk kegagalan request yang umum.

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

| Status                                   | Apa artinya biasanya                                                                                                              | Retry?         | Tindakan pertama                                                                                        |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------- |
| `400`                                    | Validasi request gagal sebelum request diproses secara normal.                                                                    | Tidak          | Validasi `model`, `messages`, bentuk JSON, dan tipe field.                                              |
| `401`                                    | API key tidak ada, salah format, atau tidak valid.                                                                                | Tidak          | Periksa `Authorization: Bearer $COMETAPI_KEY`.                                                          |
| `403`                                    | Akses diblokir atau request saat ini tidak diizinkan.                                                                             | Biasanya tidak | Retry dengan request yang sudah pasti benar dan hapus field khusus model terlebih dahulu.               |
| Path mistake                             | Base URL salah atau path endpoint salah. Di Comet ini bisa muncul sebagai redirect `301` atau HTML, bukan JSON `404` yang bersih. | Tidak          | Gunakan `https://api.cometapi.com/v1` secara tepat dan nonaktifkan auto-follow redirect saat debugging. |
| `429`                                    | Rate limiting atau saturasi sementara.                                                                                            | Ya             | Gunakan exponential backoff dengan jitter.                                                              |
| `500` with `error.code: invalid_request` | Request yang salah format muncul melalui respons berstatus server.                                                                | Tidak          | Perbaiki body request sebelum retry.                                                                    |
| `500`, `503`, `504`, `524`               | Kegagalan platform, provider, atau kelas timeout.                                                                                 | Ya             | Retry dengan backoff dan simpan request id.                                                             |

## Error envelope

Banyak kegagalan CometAPI menggunakan body error seperti ini:

```json theme={null}
{
	"error": {
		"message": "...",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
```

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:

```json theme={null}
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
```

Ganti `your-model-id` dengan model ID saat ini dari [halaman Models CometAPI](/id/overview/models).

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`:

```json theme={null}
{
	"error": {
		"message": "field messages is required (request id: ...)",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
```

Jika respons `500` memiliki `error.code: invalid_request`, perlakukan itu sebagai masalah request:

1. Perbaiki body request.
2. Bandingkan payload dengan skema endpoint.
3. 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:

```json theme={null}
{
	"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 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:

1. Coba lagi dengan request 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 sebelum menghubungi dukungan.

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

## 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:

```text theme={null}
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`

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:

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

## `429 Too Many Requests`

Anggap `429` dapat dicoba ulang:

1. Gunakan exponential backoff dengan jitter.
2. Kurangi konkurensi burst.
3. 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](/api/text/chat).

## `503`, `504`, dan `524`

Status-status ini adalah **kegagalan sisi server atau kelas timeout**.

Panduan praktis:

* `503`: layanan route atau provider sementara tidak tersedia
* `504` dan `524`: kegagalan kelas timeout antara platform, edge, atau layanan provider

Yang harus dilakukan:

1. Coba lagi dengan backoff.
2. Simpan `request id`, endpoint, model, dan timestamp.
3. 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 sama
* `request 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

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

Ini secara signifikan mempercepat waktu penanganan dukungan.