> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Penanganan Kesalahan

> Struktur respons GOWA, kode kesalahan dan status HTTP, serta cara menanganinya.

## Struktur respons

Setiap respons JSON memiliki bentuk yang sama:

```json theme={null}
{
  "code": "SUCCESS",
  "message": "Success",
  "results": { }
}
```

| Kolom | Deskripsi |
| - | - |
| `code` | `SUCCESS` atau kode kesalahan. Gunakan bersama status HTTP untuk menentukan alur penanganan. |
| `message` | Detail yang dapat dibaca manusia. Teksnya dapat berubah antarversi; jangan mengurai teks ini secara programatis. |
| `results` | Payload saat berhasil. Biasanya tidak disertakan saat terjadi kesalahan. |

## Kode kesalahan

| Kode | HTTP | Arti | Tindakan |
| - | - | - | - |
| `VALIDATION_ERROR` | 400 | Kolom tidak diisi atau tidak valid. `message` menyebutkan kolomnya. | Perbaiki permintaan. |
| `INVALID_JID` | 400 | Nomor tidak terdaftar di WhatsApp, atau format JID salah. | Periksa nomor; jangan coba ulang. |
| `ALREADY_LOGGED_IN` | 400 | Login diminta untuk perangkat yang sudah login. | Tidak perlu tindakan, atau logout terlebih dahulu. |
| `DEVICE_ID_REQUIRED` | 400 | Perangkat tidak diberikan dan server memiliki nol atau beberapa perangkat. | Kirim `X-Device-Id`. |
| `AUTHENTICATION_ERROR` | 401 | Perangkat belum login ke WhatsApp (atau autentikasi WhatsApp gagal). | Periksa `/devices/{id}/status`; tautkan ulang jika perlu. |
| `NOT_FOUND` | 404 | Sumber daya tidak ditemukan (pesan, chat, jadwal…). | Periksa ID. |
| `DEVICE_NOT_FOUND` | 404 | `X-Device-Id` merujuk perangkat yang tidak dikenal. | Periksa ID slot atau JID. |
| `AVATAR_HIDDEN` | 403 | Foto profil disembunyikan oleh pengaturan privasi. | Jangan anggap ini sebagai konfirmasi bahwa foto tidak ada, atau menghapus foto dalam cache hanya berdasarkan hasil ini. |
| `AVATAR_NOT_SET` | 404 | Kontak tidak memiliki foto profil. | Hapus foto dalam cache hanya setelah memeriksa kode ini, bukan sembarang respons 404. |
| `CROSS_SITE_REQUEST_BLOCKED` | 403 | Origin browser tidak dipercaya. | Sajikan dashboard melalui HTTP(S) dan konfigurasikan origin tepercaya secara persis. |
| `CONTEXT_ERROR` | 408 | Operasi dibatalkan atau mengalami timeout secara internal. | Coba ulang satu kali. |
| `WA_REACHOUT_TIMELOCK` | 429 | WhatsApp memblokir sementara chat baru dari akun ini. | Hentikan upaya menghubungi kontak baru; lihat [Batas pengiriman](https://gowa-docs.mintlify.site/id/advanced/rate-limiting.md). |
| `INTERNAL_SERVER_ERROR` | 500 | Kegagalan tak terduga, termasuk panic yang dipulihkan. | Coba ulang dengan jeda bertahap; periksa log. |
| `QR_CHANNEL_ERROR` | 500 | Tidak dapat memperoleh kode QR. | Coba login ulang. |
| `SESSION_SAVED_ERROR` | 500 | Tidak dapat menyimpan sesi. | Periksa penyimpanan dan izin. |
| `UPLOAD_MEDIA_ERROR` | 500 | Pengunggahan media ke WhatsApp gagal. | Coba ulang; periksa ukuran dan format. |
| `WEBHOOK_ERROR` | 500 | Kesalahan konfigurasi atau pengiriman webhook. | Periksa URL webhook. |
| `INVALID_WA_CLI` | 500 | Klien WhatsApp perangkat belum diinisialisasi. | Sambungkan kembali atau login ulang. |
| `DEVICE_MANAGER_UNAVAILABLE` | 503 | Pengelola perangkat belum diinisialisasi. | Coba lagi sebentar lagi; periksa log startup. |
| `GATEWAY_TIMEOUT` | 504 | Permintaan melebihi 45 detik. | Tindakan mungkin tetap selesai; periksa sebelum mencoba ulang. |

Kegagalan Basic Auth mengembalikan `401` dari lapisan autentikasi sebelum mencapai handler GOWA; anggap setiap `401` tanpa `code` GOWA sebagai kredensial yang salah.

## Mencoba ulang dengan aman

Pengiriman **tidak idempoten**: GOWA tidak memiliki kunci idempotensi. Jika pengiriman mengalami timeout (`504`, kesalahan jaringan), pesan mungkin sudah terkirim. Sebelum mengirim ulang, periksa chat dengan `GET /chat/{chat_jid}/messages?is_from_me=true&limit=5`, atau terima risiko duplikasi.

| Coba ulang | Jangan coba ulang |
| - | - |
| `500 INTERNAL_SERVER_ERROR`, `UPLOAD_MEDIA_ERROR`, `CONTEXT_ERROR`, `503` | Kesalahan `400`, `INVALID_JID`, `404`, `401`, `WA_REACHOUT_TIMELOCK` |

Gunakan jeda eksponensial dengan batas maksimum, dan batasi jumlah percobaan.

```javascript theme={null}
async function gowa(path, body, attempt = 1) {
  const res = await fetch(`http://localhost:3000${path}`, {
    method: "POST",
    headers: {
      Authorization: "Basic " + Buffer.from("admin:changeme").toString("base64"),
      "Content-Type": "application/json",
      "X-Device-Id": "my-device",
    },
    body: JSON.stringify(body),
  });
  const data = await res.json().catch(() => ({}));
  if (res.ok) return data.results;

  const retryable = [500, 503].includes(res.status) && data.code !== "INVALID_JID";
  if (retryable && attempt < 4) {
    await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
    return gowa(path, body, attempt + 1);
  }
  throw Object.assign(new Error(data.message || res.statusText), { code: data.code, status: res.status });
}
```

## Debugging

* Jalankan dengan `APP_DEBUG=true` untuk log terperinci.
* Periksa perangkat: `GET /devices/{device_id}/status` (`is_connected`, `is_logged_in`).
* `GET /health` hanya mengonfirmasi bahwa proses dan database berjalan; endpoint ini tidak memeriksa konektivitas WhatsApp.


## Related topics

- [Penanganan Media](https://gowa-docs.mintlify.site/id/examples/media-handling.md)
- [Tarik Pesan](https://gowa-docs.mintlify.site/id/api-reference/message/tarik-pesan.md)
- [Hubungkan kembali perangkat](https://gowa-docs.mintlify.site/id/api-reference/device/hubungkan-kembali-perangkat.md)
- [Daftar langganan pembaruan langsung perangkat](https://gowa-docs.mintlify.site/id/api-reference/newsletter/daftar-langganan-pembaruan-langsung-perangkat.md)
- [Hapus perangkat](https://gowa-docs.mintlify.site/id/api-reference/device/hapus-perangkat.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.