> For the complete documentation index, see [llms.txt](https://docs.watzap.id/help/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.watzap.id/help/integrations/solusi-kendala-kirim-pesan-via-api.md).

# Solusi Kendala Kirim Pesan via API

Arti kode respons Rest API WatZap (1001 sampai 1005, 3001, dan Limit Exceeded) beserta penyebab dan solusinya, batas kirim per paket, cara menguji permintaan, dan cara membaca API Log Report.

Setiap permintaan ke Rest API WatZap dibalas dalam format JSON. Kalau pesan tidak terkirim, kolom `status` dan `message` di respons itu menunjukkan penyebabnya.

Panduan ini membahas endpoint untuk nomor di tab **API** yang memakai **Number Key**: `send_message`, `send_image_url`, `send_file_url`, `validate_number`, `send_message_group`, dan `send_file_group`.

## Cek dulu 4 hal ini

1. **Metode dan alamat.** Kirim permintaan dengan metode `POST` ke `https://api.watzap.id/v1/<nama-endpoint>`, misalnya `https://api.watzap.id/v1/send_message`. Isi body dalam format JSON dengan header `Content-Type: application/json`. Kalau metodenya bukan `POST`, server hanya membalas teks `Invalid Request Method, RAY ID: …`.
2. **API Key dan Number Key.** Salin ulang dengan tombol salin, jangan diketik manual. Panduannya: [Mendapatkan API Key di Member Area](https://docs.watzap.id/help/integrations/mendapatkan-api-key-di-member-area.md) dan [Mendapatkan Number Key untuk API](https://docs.watzap.id/help/integrations/mendapatkan-number-key-untuk-api.md).
3. **Nomor API berstatus Online.** Cek di menu **WhatsApp** → tab **API** (lihat gambar di bawah).
4. **Paket Plus atau Premium yang masih aktif.** Kirim pesan lewat Rest API tidak tersedia di paket Free, Personal, dan paket lama (Lite, Pro, Business).

Di menu **WhatsApp** (bagian **WA UNOFFICIAL**):

1. Klik tab **API**.
2. **Status** harus **Online**. Kalau **Offline** seperti contoh ini, pesan dari nomor tersebut gagal dikirim.
3. **Number Key** di baris ini harus sama persis dengan isi parameter `number_key`.
4. Klik **Connect** lalu scan QR Code lagi untuk menyambungkan nomor yang Offline.

![Tab API: status nomor, Number Key, dan tombol Connect (Number Key diburamkan)](https://4182233851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5hxDGBLGZN4N69IP4zHp%2Fuploads%2FrljoKLlX0bsSKwOLyLLM%2FM1-2-01-cek-nomor-api.png?alt=media)

## Cara membaca respons

Status HTTP respons selalu **200**, termasuk saat permintaan gagal. Jadi, yang menentukan berhasil atau gagal adalah kolom `status` di dalam JSON:

* `"status": "200"` dan `"ack": "successfully"`: permintaan diterima dan diteruskan ke nomor API. Respons `send_message` juga berisi `number_key` dan `sender_number`, yaitu nomor yang dipakai untuk mengirim.
* Kode lain (misalnya `"1003"`) dan `"ack": "fatal_error"`: permintaan gagal. Cocokkan kodenya dengan tabel di bawah.
* `"status": false`: batas jumlah panggilan terlampaui.

Contoh respons gagal:

```json
{
  "status": "1003",
  "message": "License Not Found",
  "ack": "fatal_error"
}
```

{% hint style="info" %}
Nilai `status` berupa teks, misalnya `"200"` atau `"1003"`, kecuali saat batas panggilan terlampaui: nilainya `false` (boolean). Pastikan kode program Kamu menangani keduanya.
{% endhint %}

## Daftar kode respons

| `status` | `message`                                                                                                                                                         | Penyebab                                                                                                                                                                                                                   | Solusi                                                                                                                                             |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`    | Pesan dari server                                                                                                                                                 | Berhasil, permintaan diteruskan ke nomor API.                                                                                                                                                                              | -                                                                                                                                                  |
| `1001`   | `Wrong Parameters`                                                                                                                                                | Ada parameter wajib yang kosong atau salah nama, atau body tidak dikirim sebagai JSON.                                                                                                                                     | Lengkapi parameter sesuai [tabel parameter wajib](#parameter-wajib-per-endpoint).                                                                  |
| `1001`   | `Wrong Parameters: phone_no too short`                                                                                                                            | Nomor tujuan kurang dari 5 digit (dicek di `send_message` dan `send_file_url`).                                                                                                                                            | Tulis nomor tujuan lengkap, misalnya `6281200001234`.                                                                                              |
| `1001`   | `Domain Not Allowed`                                                                                                                                              | Parameter `host` ikut dikirim, tetapi domainnya belum terdaftar untuk API Key Kamu. Parameter ini dipakai [Plugin WatZap di WordPress](https://docs.watzap.id/help/integrations/memasang-plugin-watzap-di-wordpress.md).   | Kalau bukan dari plugin, hapus parameter `host`. Kalau dari plugin, sambungkan ulang API Key di pengaturan plugin pada domain tersebut.            |
| `1002`   | `Invalid Secret Key`                                                                                                                                              | API Key salah, terpotong, atau ikut tersalin spasi.                                                                                                                                                                        | Salin ulang dengan tombol **Copy** di menu **API Key**.                                                                                            |
| `1003`   | `License Not Found`                                                                                                                                               | Number Key tidak ditemukan: salah ketik, nomornya sudah dihapus, atau Number Key lama (nomor yang dipindah tab mendapat Number Key baru). Dengan `number_key` `ALL`, muncul bila tidak ada satu pun nomor API yang Online. | Salin ulang Number Key dari tab API. Pastikan minimal satu nomor API Online. Nilai `ALL` hanya berlaku di `send_message` dan `send_message_group`. |
| `1003`   | `Your Package is Expired`                                                                                                                                         | Masa aktif paket sudah habis.                                                                                                                                                                                              | Perpanjang paket: [Cara Perpanjang Paket Langganan](https://docs.watzap.id/help/subscription/cara-perpanjang-paket-langganan.md).                  |
| `1004`   | `Pairing Failed, Access Denied`                                                                                                                                   | Number Key milik akun WatZap lain, bukan akun pemilik API Key.                                                                                                                                                             | Pakai API Key dan Number Key dari akun yang sama.                                                                                                  |
| `1005`   | Pesan dari server WhatsApp, atau `Kami gagal mengirimkan pesan dikarenakan ada masalah pada koneksi WhatsApp anda, mohon rekoneksikan ulang nomor WhatsApp anda.` | Nomor API gagal mengirim, biasanya karena nomor Offline atau WhatsApp di HP pengirim terputus. Di `validate_number`, kode ini berarti pengecekan nomor gagal; baca isi `message`.                                          | Cek status nomor di tab API. Kalau Offline, klik **Connect** dan scan QR Code lagi.                                                                |
| `3001`   | `Need Upgrade Package`                                                                                                                                            | Paket Kamu bukan Plus atau Premium, termasuk paket lama (Lite, Pro, Business).                                                                                                                                             | Upgrade paket: [Cara Mengganti Paket Langganan](https://docs.watzap.id/help/subscription/cara-mengganti-paket-langganan.md).                       |
| `false`  | `Limit Exceeded Please Try Again, in 1 Minutes` (di beberapa endpoint diikuti `Total Call For This Minutes (…)`)                                                  | Terlalu banyak panggilan dalam 1 menit untuk satu Number Key. Lihat [Batas pengiriman](#batas-pengiriman).                                                                                                                 | Beri jeda antar-pesan dan ulangi di menit berikutnya, atau bagi pengiriman ke beberapa nomor API.                                                  |
| `false`  | `Limit Exceeded Please Try Again, in 1 Hours, Total Call For Last 24 Hours (…)`                                                                                   | Batas kirim 24 jam untuk satu Number Key sudah tercapai.                                                                                                                                                                   | Tunggu lalu kirim lagi, bagi pengiriman ke beberapa nomor API, atau naikkan paket.                                                                 |

{% hint style="info" %}
Respons hanya menampilkan kendala pertama yang ditemukan. Setelah satu kendala beres, kirim ulang permintaan untuk memastikan tidak ada kendala lain.
{% endhint %}

## Parameter wajib per endpoint

| Endpoint             | Parameter wajib                                | Catatan                                      |
| -------------------- | ---------------------------------------------- | -------------------------------------------- |
| `send_message`       | `api_key`, `number_key`, `phone_no`, `message` | `number_key` boleh diisi `ALL`.              |
| `send_image_url`     | `api_key`, `number_key`, `phone_no`, `url`     | `message` opsional, dipakai sebagai caption. |
| `send_file_url`      | `api_key`, `number_key`, `phone_no`, `url`     |                                              |
| `validate_number`    | `api_key`, `number_key`, `phone_no`            |                                              |
| `send_message_group` | `api_key`, `number_key`, `group_id`, `message` | `number_key` boleh diisi `ALL`.              |
| `send_file_group`    | `api_key`, `number_key`, `group_id`, `url`     |                                              |

Nomor tujuan (`phone_no`) boleh ditulis `08…` atau `628…`. WatZap otomatis mengubahnya ke format `62…` serta membuang tanda `+`, spasi, dan tanda hubung. Untuk nomor luar negeri, tulis lengkap dengan kode negaranya.

## Batas pengiriman

Batas dihitung per **Number Key** dan per endpoint. Semakin banyak nomor API yang Kamu pakai, semakin besar total kapasitas kirimnya.

| Batas per Number Key        | Personal | Plus  | Premium |
| --------------------------- | -------- | ----- | ------- |
| Kirim pesan per 24 jam      | 5.000    | 7.000 | 10.000  |
| Kirim pesan per menit       | 30       | 30    | 30      |
| `validate_number` per menit | -        | 50    | 50      |

Batas Personal hanya berlaku untuk integrasi yang boleh dipakai paket Personal, seperti [Google Form](https://docs.watzap.id/help/integrations/integrasi-dengan-google-form.md). Pemanggilan Rest API langsung dari paket Personal dijawab `Need Upgrade Package`.

## Menguji permintaan dari halaman API Key

Kamu bisa mencoba endpoint langsung dari dashboard tanpa menulis kode.

{% stepper %}
{% step %}

### Buka endpoint di tab Legacy

Buka menu **INTEGRATIONS** → **API Key**, klik tab **Legacy**, lalu klik baris endpoint yang ingin dicoba, misalnya `/send_message`. Letak tab ini dijelaskan di [Mendapatkan API Key di Member Area](https://docs.watzap.id/help/integrations/mendapatkan-api-key-di-member-area.md#daftar-endpoint-di-halaman-api-key).
{% endstep %}

{% step %}

### Isi body lalu jalankan

Klik **Try it out** di baris **PARAMETERS**, lalu:

1. Ubah isi **Example Value** dengan data Kamu.
2. Klik **Execute**.
3. Baca hasilnya di bagian **Response**.

![Try it out pada endpoint /send\_message](https://4182233851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5hxDGBLGZN4N69IP4zHp%2Fuploads%2FGTWl0NNTOuAk8jUt5edm%2FM1-2-04-try-it-out.png?alt=media)

Contoh di atas memakai `YOUR_API_KEY`, sehingga dijawab `1002` `Invalid Secret Key` walaupun labelnya **Response 200**. Kode HTTP 400 dan 401 di tabel **RESPONSES** hanya gambaran. Patokannya tetap kolom `status`.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**Execute** mengirim permintaan sungguhan. Kalau API Key, Number Key, dan nomor tujuannya benar, pesan benar-benar terkirim. Untuk uji coba, kirim ke nomor Kamu sendiri.
{% endhint %}

## Mengecek API Log Report (khusus WABA Official)

Menu **API Log Report** di bagian **INTEGRATIONS** mencatat pengiriman lewat API **WABA Official** (endpoint berawalan `waba_`, misalnya `waba_send_message`).

![Menu INTEGRATIONS → API Log Report](https://4182233851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5hxDGBLGZN4N69IP4zHp%2Fuploads%2F7JnI8LgiS6oMH6LAFvtO%2FM1-2-02-menu-api-log.png?alt=media)

{% hint style="info" %}
Pengiriman lewat Number Key (endpoint di tab **Legacy**, seperti `send_message`) tidak tercatat di API Log Report. Untuk endpoint tersebut, cek kendalanya dari respons JSON seperti dijelaskan di atas.
{% endhint %}

Di halaman **API Log Report**:

1. Data yang ditampilkan hanya **7 hari terakhir**.
2. **Filters** untuk menyaring status: **All Status**, **Success**, **Sent**, **Delivered**, **Read**, atau **Failed**.
3. Label **FAILED**: arahkan kursor ke label ini untuk melihat pesan error dari API, misalnya `Template not found`.

![API Log Report dengan status FAILED dan keterangan errornya (contoh data)](https://4182233851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5hxDGBLGZN4N69IP4zHp%2Fuploads%2F7EeLhFMlHLS9m8h1MD1G%2FM1-2-03-api-log-report.png?alt=media)

Kolom **TEMPLATE NAME** berisi nama template, atau nama endpoint (misalnya `send_message`) untuk pesan biasa. Pakai kolom pencarian untuk mencari nama template, nama endpoint, nomor tujuan, atau isi pesan, **Export CSV** untuk mengunduh data, dan **Refresh Data** untuk memuat ulang.

## Masalah umum

<details>

<summary>Respons status 200, tapi pesan tidak sampai</summary>

Status `200` berarti permintaan sudah diterima dan diteruskan ke nomor API. Kalau pesan tetap tidak sampai:

* Pastikan nomor tujuan aktif di WhatsApp. Cek dulu dengan endpoint `validate_number`.
* Pastikan HP nomor pengirim tetap tersambung ke internet dan perangkat tertaut WatZap tidak dilepas.
* Lihat `sender_number` di respons untuk tahu nomor mana yang mengirim, terutama kalau `number_key` diisi `ALL`.

</details>

<details>

<summary>Kemarin berhasil, sekarang muncul License Not Found</summary>

Number Key berubah setiap kali nomor dipindah ke tab API (lewat **Assign for API**) atau ditambahkan ulang. Salin Number Key terbaru dari tab API, lalu perbarui pengaturan di aplikasi atau kode Kamu.

</details>

<details>

<summary>Nomor API sering Offline</summary>

WatZap tidak memutus nomor API secara otomatis. Nomor API biasanya Offline karena perangkat tertaut dilepas dari HP atau WhatsApp di HP keluar. Klik **Connect** dan scan QR Code lagi. Penjelasannya ada di [Perbedaan Nomor Broadcast dan API](https://docs.watzap.id/help/connect-to-whatsapp/perbedaan-nomor-broadcast-dan-api.md).

</details>

<details>

<summary>Pakai WatZap SDK</summary>

Kalau Kamu memakai JavaScript atau Node.js, [WatZap SDK (JavaScript)](https://docs.watzap.id/help/integrations/watzap-sdk.md) sudah membungkus pemanggilan endpoint dan respons di atas.

</details>
