Referensi

Daftar Kode Error

Referensi lengkap kode error API whatsGo, penyebab umum, dan cara mengatasinya.

Setiap error dikembalikan dalam format envelope yang konsisten. Berikut contohnya:

{
  "success": false,
  "error": {
    "code": "VALIDATION_INVALID_PHONE",
    "message": "Format nomor telepon tidak valid",
    "details": {
      "field": "to",
      "hint": "Gunakan format kode negara + nomor (contoh: 628123456789)"
    }
  }
}

Field error.details bersifat opsional — beberapa error tidak menyertakannya.

Autentikasi

Error autentikasi terjadi saat API key tidak valid, kedaluwarsa, atau tidak memiliki izin yang cukup.

Kode Error HTTP Penyebab Solusi
AUTH_MISSING_KEY 401 Request tidak menyertakan header Authorization. Sertakan header Authorization: Bearer wg_sk_xxxxx.
AUTH_INVALID_KEY 401 API key tidak dikenali atau sudah ditandai tidak aktif. Periksa API key di dashboard whatsGo. Buat key baru jika diperlukan.
AUTH_KEY_REVOKED 401 API key telah dicabut secara manual oleh admin. Buat API key baru dari dashboard.
AUTH_KEY_EXPIRED 401 API key sudah melewati masa berlaku. Perpanjang atau buat API key baru dari dashboard.
AUTH_INSUFFICIENT_SCOPE 403 API key tidak memiliki izin (scope) untuk endpoint yang dipanggil. Periksa scope API key di dashboard dan tambahkan izin yang diperlukan.

Validasi

Error validasi terjadi saat request body tidak sesuai dengan format atau aturan yang ditetapkan API.

Kode Error HTTP Penyebab Solusi
VALIDATION_ERROR 400 Request body mengandung field yang tidak valid secara umum. Periksa error.details untuk field spesifik yang bermasalah.
VALIDATION_INVALID_PHONE 400 Format nomor telepon tidak sesuai standar E.164. Gunakan format kode negara + nomor tanpa spasi (contoh: 6281234567890).
VALIDATION_MISSING_FIELD 400 Field wajib tidak disertakan dalam request body. Periksa dokumentasi endpoint untuk daftar field wajib.
VALIDATION_INVALID_FIELD 400 Field dikirim dengan tipe data atau nilai yang tidak sesuai. Cek tipe data yang diharapkan (string, integer, array, dll.) di dokumentasi endpoint.

WhatsApp — pengiriman umum

Error ini terjadi saat proses pengiriman pesan WhatsApp mengalami kegagalan umum, bukan terkait template atau pesan interaktif.

Kode Error HTTP Penyebab Solusi
WHATSAPP_SESSION_CLOSED 400 Sesi WhatsApp terkait saluran sudah tidak aktif atau belum diinisialisasi. Pastikan sesi WhatsApp aktif di dashboard. Hubungkan ulang jika perlu.
WHATSAPP_CHANNEL_NOT_FOUND 404 Saluran WhatsApp dengan ID yang diberikan tidak ditemukan. Periksa channelId dan pastikan saluran sudah terdaftar di akun kamu.
WHATSAPP_SEND_FAILED 502 Gagal mengirim pesan ke server Meta/WhatsApp. Ini error upstream. Coba ulangi request setelah beberapa detik. Gunakan exponential backoff.
WHATSAPP_MEDIA_UPLOAD_FAILED 400 Gagal mengunggah media (gambar, video, audio, dokumen) ke server WhatsApp. Pastikan ukuran file di bawah batas (gambar 5 MB, video 16 MB, dokumen 100 MB). Periksa format file yang didukung.

WhatsApp — template

Error ini terkait penggunaan template pesan WhatsApp. Template harus disetujui oleh Meta sebelum dapat digunakan.

Kode Error HTTP Penyebab Solusi
WHATSAPP_TEMPLATE_NOT_FOUND 404 Template dengan nama dan bahasa yang diberikan tidak ditemukan. Periksa nama dan kode bahasa template. Pastikan template sudah di-deploy ke WhatsApp Manager.
WHATSAPP_TEMPLATE_REJECTED 400 Template sedang dalam status ditolak atau belum disetujui oleh Meta. Sesuaikan isi template agar mematuhi kebijakan Meta, lalu kirim ulang untuk review.
WHATSAPP_TEMPLATE_INVALID_COMPONENTS 400 Struktur komponen template (header, body, button) tidak valid. Periksa urutan dan jumlah komponen yang dikirim agar sesuai dengan definisi template.
WHATSAPP_TEMPLATE_MISSING_BUTTON_INDEX 400 Template memiliki tombol interaktif tetapi indeks tombol tidak disertakan. Sertakan field index pada komponen button yang ingin dijalankan.
WHATSAPP_TEMPLATE_INVALID_PARAMETER_TYPE 400 Tipe parameter template tidak sesuai (mis. mengirim string untuk parameter angka). Periksa tipe data setiap parameter di WhatsApp Manager dan sesuaikan request.

WhatsApp — pesan interaktif

Error ini terkait pengiriman pesan interaktif seperti tombol cepat, list message, dan pesan location.

Kode Error HTTP Penyebab Solusi
INTERACTIVE_INVALID_TYPE 400 Tipe interaktif tidak didukung (hanya button, list, dan location_request_message). Gunakan salah satu tipe yang didukung. Periksa dokumentasi pesan interaktif.
INTERACTIVE_BUTTONS_LIMIT_EXCEEDED 400 Jumlah tombol melebihi batas (maks. 3 tombol untuk quick reply, 10 untuk URL). Kurangi jumlah tombol agar sesuai batas maksimum.
INTERACTIVE_INVALID_LIST_OPTIONS 400 Opsi list message kosong atau melebihi batas (maks. 10 section, 10 item per section). Pastikan setiap section memiliki 1–10 item dan total section tidak melebihi 10.
INTERACTIVE_MISSING_BODY 400 Body teks untuk pesan interaktif tidak disertakan. Sertakan field text.body dengan isi pesan yang menjelaskan pilihan yang tersedia.
INTERACTIVE_BODY_TOO_LONG 400 Teks body melebihi batas karakter (maks. 1.024 karakter untuk button, 80 untuk list header). Pendekkan teks body sesuai batas karakter masing-masing tipe interaktif.
INTERACTIVE_DUPLICATE_BUTTON_ID 400 ID tombol tidak unik dalam satu pesan. Pastikan setiap tombol memiliki id yang berbeda.

Resource

Error resource terkait dengan entitas yang dikelola melalui API seperti kontak, channel, dan sejenisnya.

Kode Error HTTP Penyebab Solusi
RESOURCE_NOT_FOUND 404 Resource dengan ID yang diberikan tidak ditemukan di sistem. Periksa ID resource. Gunakan endpoint list untuk memverifikasi ketersediaan data.
RESOURCE_ALREADY_EXISTS 409 Resource yang ingin dibuat sudah ada (duplikat). Gunakan metode update (PATCH) untuk mengubah data yang sudah ada, atau gunakan ID yang berbeda.

Rate limit & server

Error ini terkait pembatasan jumlah request atau gangguan di sisi server whatsGo.

Kode Error HTTP Penyebab Solusi
RATE_LIMIT_EXCEEDED 429 Melebihi batas request per menit atau per hari untuk API key tersebut. Baca header Retry-After dan tunggu sebelum mencoba ulang. Implementasikan exponential backoff.
SERVER_INTERNAL_ERROR 500 Kesalahan internal di server whatsGo yang tidak terduga. Coba ulangi request setelah beberapa detik. Jika berlanjut, hubungi tim support.
SERVER_SERVICE_UNAVAILABLE 503 Layanan sedang dalam pemeliharaan atau tidak tersedia sementara. Tunggu beberapa menit dan coba lagi. Pantau status layanan di halaman status whatsGo.

Strategi retry

Gunakan strategi retry yang tepat berdasarkan jenis error yang diterima:

Error Retryable? Strategi
401 / 403 Tidak Perbaiki kredensial atau scope. Jangan retry tanpa perubahan.
400 (validasi) Tidak Perbaiki request body berdasarkan pesan error lalu kirim ulang.
404 Tidak Verifikasi ID atau path. Retry tidak akan mengubah hasil.
409 Tidak Resource sudah ada — gunakan update, bukan create.
429 Ya Tunggu sesuai header Retry-After, lalu coba ulangi. Gunakan exponential backoff.
500 Ya Tunggu 1–5 detik, lalu coba ulangi. Jika berlanjut >3 kali, hubungi support.
502 Ya Error upstream — tunggu 2–10 detik, lalu coba ulangi dengan exponential backoff.
503 Ya Layanan sedang tidak tersedia — tunggu beberapa menit sebelum retry.
Tips penting

Selalu gunakan Idempotency-Key saat retry request POST untuk menghindari duplikasi pesan. Terapkan exponential backoff (1s → 2s → 4s → 8s) dengan batas maksimal retry 5 kali untuk error 5xx dan 429.