Kode Error & Troubleshooting

Setiap response error dari API mengikuti format yang seragam:

{
  "error": "deskripsi singkat masalah"
}

---

Daftar Kode Status HTTP

2xx — Berhasil

Kode	Nama	Artinya
200 OK	Berhasil	Request berhasil, data ada di body response
202 Accepted	Diterima	Pesan diterima dan masuk antrean (pengiriman asinkron)

4xx — Kesalahan dari Sisi Anda

Kode	Nama	Artinya	Yang Harus Dilakukan
400 Bad Request	Request Tidak Valid	Field wajib kosong, format salah, atau kombinasi field tidak valid	Periksa body request — baca pesan error untuk detail field mana yang bermasalah
401 Unauthorized	Tidak Terautentikasi	API key tidak disertakan atau tidak valid	Pastikan header Authorization: Bearer wag_xxx ada dan key-nya benar
403 Forbidden	Tidak Diizinkan	ToS belum disetujui, akun disuspend, atau sesi bukan milik akun Anda	Setujui ToS, cek status akun, atau pastikan session_id milik akun Anda
409 Conflict	Konflik	Sesi tidak sedang dihosting worker (offline)	Tunggu sesi online, atau lakukan pairing ulang
429 Too Many Requests	Rate Limit	Terlalu banyak request dalam waktu singkat	Lihat header Retry-After, tunggu sebelum retry — lihat Rate Limit

5xx — Kesalahan dari Sisi Server

Kode	Nama	Artinya	Yang Harus Dilakukan
500 Internal Server Error	Error Internal	Terjadi kesalahan tak terduga di server	Coba ulang setelah beberapa saat; hubungi support jika berlanjut
502 Bad Gateway	Gateway Error	Server gagal meneruskan ke komponen internal (misal: broker pesan)	Aman untuk retry — gunakan Idempotency-Key yang sama agar tidak kirim pesan ganda

---

Error Umum & Solusinya

"session does not belong to this user"

Sesi yang Anda sebut di session_id tidak terdaftar di akun Anda.

• Pastikan session_id yang dipakai adalah hasil pairing dari akun Anda sendiri
• Cek dari Dashboard → Sesi untuk melihat session_id yang aktif

---

"session is not currently hosted by any worker"

Sesi ada di database, tapi tidak sedang terhubung ke WhatsApp saat ini.

Kemungkinan penyebab:

• Server baru restart, sesi sedang dalam proses reconnect (tunggu ~10 detik, coba lagi)
• Nomor WhatsApp di-logout dari perangkat tertaut di HP — perlu pairing ulang
• Sesi belum pernah paired sama sekali

---

"tos not accepted" / "terms of service not accepted"

Akun Anda belum menyetujui Terms of Service. Selama itu, seluruh endpoint /v1/* membalas 403 — bukan hanya pengiriman pesan.

• Login ke Dashboard → Pengaturan, baca dan setujui ketentuannya
• Cek GET /v1/tos untuk mengetahui versi yang menunggu persetujuan — berguna untuk membedakan error ini dari masalah API key di penanganan error Anda
• Persetujuan tidak bisa dilakukan lewat API: perjanjian hukum harus disetujui orang yang membaca dokumennya, bukan oleh API key

---

"rate limit exceeded"

Anda mengirim terlalu banyak pesan dalam waktu singkat.

• Lihat header Retry-After di response — nilai dalam detik sebelum boleh coba lagi
• Implementasikan exponential backoff: tunggu 1s, lalu 2s, lalu 4s, dst
• Lihat batas rate limit di halaman Rate Limit

---

Cara Debug

1. Baca field error di response body

Pesan error dirancang untuk menjelaskan masalahnya secara langsung:

{
  "error": "media_type and media_url are required together"
}

2. Perhatikan kode status HTTP

• 4xx = masalah ada di request Anda → perbaiki request
• 5xx = masalah di server → retry dengan key yang sama

3. Gunakan Idempotency-Key yang sama saat retry

Untuk 5xx, aman untuk retry. Gunakan Idempotency-Key yang sama — server akan mengenali ini sebagai retry, bukan request baru, sehingga tidak ada pesan ganda.