API & Integrasi
Daftar Kode Error Referensi lengkap kode error API Chatera, penyebab umum, dan cara mengatasinya.
Semua error dari API Chatera memakai envelope yang sama:
{ "success" : false , "error" : { "code" : "VALIDATION_INVALID_PHONE" , "message" : "Format nomor telepon tidak valid" , "details" : { "field" : "to" , "hint" : "..." } } } error.code adalah identifier mesin yang stabil — pakai untuk
branching logic di handler kamu (jangan parse message, karena
kalimatnya bisa berubah).
Kode HTTP Penyebab Solusi AUTH_MISSING_KEY401 Header Authorization / X-API-Key tidak dikirim Tambah header autentikasi AUTH_INVALID_KEY401 Key tidak valid (salah ketik, prefix salah, atau tidak ada di DB) Cek key, pastikan diawali chatera_sk_ atau chatera_pk_ AUTH_KEY_REVOKED401 Key dicabut dari dashboard Buat key baru AUTH_KEY_EXPIRED401 Key memiliki masa berlaku dan sudah lewat Buat key baru AUTH_INSUFFICIENT_SCOPE403 Key tidak punya scope yang dibutuhkan endpoint Buat key baru dengan scope yang sesuai
Kode HTTP Penyebab Solusi VALIDATION_ERROR400 Generic validation failure Lihat details.errors[] VALIDATION_INVALID_PHONE400 Format nomor tidak valid Pakai E.164 (628xxx atau +628xxx) VALIDATION_MISSING_FIELD400 Field wajib tidak ada Lihat details.field untuk nama field VALIDATION_INVALID_FIELD400 Format field tidak valid (panjang, tipe, regex) Lihat details.hint
Kode HTTP Penyebab Solusi WHATSAPP_SESSION_CLOSED400 Di luar jendela 24 jam Pakai template WHATSAPP_CHANNEL_NOT_FOUND404 channel_id tidak valid, atau >1 saluran tanpa channel_idCek saluran aktif di dashboard WHATSAPP_SEND_FAILED502 Meta menolak request Lihat details. Coba lagi setelah beberapa saat. WHATSAPP_MEDIA_UPLOAD_FAILED400 URL media tidak bisa di-fetch Meta (404, timeout, terlalu besar) Pastikan URL HTTPS publik dan ukuran sesuai limit Meta
Kode HTTP Penyebab Solusi WHATSAPP_TEMPLATE_NOT_FOUND404 Nama template salah / belum approved Cek di Meta Business Manager WHATSAPP_TEMPLATE_REJECTED400 Template ditolak Meta Buat ulang di Meta Business Manager WHATSAPP_TEMPLATE_INVALID_COMPONENTS400 Struktur components tidak valid Lihat details.errors[] WHATSAPP_TEMPLATE_MISSING_BUTTON_INDEX400 Komponen button tanpa index Tambah index: 0 (atau posisi yang tepat) WHATSAPP_TEMPLATE_INVALID_PARAMETER_TYPE400 Tipe parameter tidak cocok untuk komponen Mis. currency di header tidak diperbolehkan
Kode HTTP Penyebab Solusi WHATSAPP_INTERACTIVE_INVALID_TYPE400 interactive.type tidak dikenalPakai button, list, atau cta_url WHATSAPP_INTERACTIVE_MISSING_FIELD400 Field wajib tidak ada Cek details.field WHATSAPP_INTERACTIVE_INVALID_FIELD400 Format field tidak valid (URL, panjang, dll) Cek details.hint WHATSAPP_INTERACTIVE_LIMIT_EXCEEDED400 Melebihi batas tombol/section/karakter Lihat tabel batas di Pesan Interaktif
Kode HTTP Penyebab Solusi RESOURCE_NOT_FOUND404 Resource (kontak, percakapan, template) tidak ditemukan Cek ID yang dikirim RESOURCE_ALREADY_EXISTS409 Resource dengan identifier yang sama sudah ada (mis. kontak dengan nomor sama) Pakai endpoint list / update untuk modify resource yang ada
Kode HTTP Penyebab Solusi RATE_LIMIT_EXCEEDED429 Melebihi batas request per menit / per hari Tunggu beberapa saat. Lihat header X-RateLimit-Reset. SERVER_INTERNAL_ERROR500 Error tidak terduga di server Chatera Coba lagi dengan exponential backoff. Hubungi support kalau berlanjut. SERVER_SERVICE_UNAVAILABLE503 Layanan sedang maintenance / overload Coba lagi dalam beberapa menit
Tidak semua error layak di-retry. Aturan umum:
HTTP Retry? 4xx (kecuali 429)Jangan retry — perbaiki request kamu dulu429Ya, dengan exponential backoff. Hormati header X-RateLimit-Reset 500, 502, 503, 504Ya, dengan exponential backoff (1s → 2s → 4s → 8s) Network error / timeout Ya, dengan exponential backoff
Jangan retry pesan WhatsApp tanpa idempotency
Kalau request POST /v1/whatsapp/messages mengembalikan timeout
network (bukan 4xx/5xx dari server), pesan mungkin sudah dikirim.
Cek webhook message.sent sebelum retry, atau implementasikan
deduplication di sisi kamu (lihat Konvensi ).