Daftar Kode Error

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).

Isi error.details bervariasi per kode error:

Field `details`	Muncul di	Isi
`details.field` + `details.hint`	Error validasi	Nama field yang bermasalah + petunjuk perbaikan
`details.errors[]`	Validasi multi-field (mis. komponen template)	Array `{ field, message }`
`details.error`	`WHATSAPP_SEND_FAILED`	Pesan error asli dari Meta, diteruskan apa adanya — mis. `(#132001) Template name does not exist in the translation`. Ini sumber informasi paling akurat saat pengiriman ditolak Meta

Autentikasi

Kode	HTTP	Penyebab	Solusi
`AUTH_MISSING_KEY`	401	Header `Authorization` / `X-API-Key` tidak dikirim	Tambah header autentikasi
`AUTH_INVALID_KEY`	401	Key tidak valid (salah ketik, prefix salah, atau tidak ada di DB)	Cek key, pastikan diawali `chatera_sk_` atau `chatera_pk_`
`AUTH_KEY_REVOKED`	401	Key dicabut dari dashboard	Buat key baru
`AUTH_KEY_EXPIRED`	401	Key memiliki masa berlaku dan sudah lewat	Buat key baru
`AUTH_INSUFFICIENT_SCOPE`	403	Key tidak punya scope yang dibutuhkan endpoint	Buat key baru dengan scope yang sesuai

Validasi

Kode	HTTP	Penyebab	Solusi
`VALIDATION_ERROR`	400	Generic validation failure	Lihat `details.errors[]`
`VALIDATION_INVALID_PHONE`	400	Format nomor tidak valid	Pakai E.164 (`628xxx` atau `+628xxx`)
`VALIDATION_MISSING_FIELD`	400	Field wajib tidak ada — termasuk `channel_id` saat organisasi punya lebih dari satu saluran WhatsApp aktif	Lihat `details.field` untuk nama field
`VALIDATION_INVALID_FIELD`	400	Format field tidak valid (panjang, tipe, regex). Juga dipakai untuk pesan `reaction`, `sticker`, dan `contacts` yang field-nya kurang, serta `reaction.message_id` (UUID Chatera) yang tidak ditemukan	Lihat `details.hint` atau `details.errors[]`

WhatsApp — pengiriman umum

Kode	HTTP	Penyebab	Solusi
`WHATSAPP_SESSION_CLOSED`	403	Di luar jendela 24 jam (semua tipe selain `template`, termasuk `reaction`, `sticker`, `contacts`)	Pakai template
`WHATSAPP_CHANNEL_NOT_FOUND`	404	`channel_id` tidak valid / tidak aktif, atau organisasi belum punya saluran WhatsApp aktif	Cek saluran aktif di dashboard
`WHATSAPP_SEND_FAILED`	500	Meta menolak request	Baca `details.error` (pesan asli Meta). Untuk `#132001` lihat troubleshooting template. Error 5xx boleh di-retry dengan backoff.
`WHATSAPP_MEDIA_UPLOAD_FAILED`	500	Dicadangkan, saat ini belum dikembalikan endpoint mana pun. URL media yang gagal di-fetch Meta biasanya dilaporkan belakangan lewat webhook `message.failed`	Pastikan URL HTTPS publik dan ukuran sesuai limit Meta

WhatsApp — template

Kode	HTTP	Penyebab	Solusi
`WHATSAPP_TEMPLATE_NOT_FOUND`	404	Nama template salah / belum approved	Cek di Meta Business Manager
`WHATSAPP_TEMPLATE_REJECTED`	400	Template ditolak Meta	Buat ulang di Meta Business Manager
`WHATSAPP_TEMPLATE_INVALID_COMPONENTS`	400	Struktur `components` tidak valid	Lihat `details.errors[]`
`WHATSAPP_TEMPLATE_MISSING_BUTTON_INDEX`	400	Komponen `button` tanpa `index`	Tambah `index: 0` (atau posisi yang tepat)
`WHATSAPP_TEMPLATE_INVALID_PARAMETER_TYPE`	400	Tipe parameter tidak cocok untuk komponen	Mis. `currency` di `header` tidak diperbolehkan

WhatsApp — pesan interaktif

Kode	HTTP	Penyebab	Solusi
`WHATSAPP_INTERACTIVE_INVALID_TYPE`	400	`interactive.type` tidak dikenal	Pakai `button`, `list`, `cta_url`, atau `location_request_message`
`WHATSAPP_INTERACTIVE_MISSING_FIELD`	400	Field wajib tidak ada	Cek `details.field`
`WHATSAPP_INTERACTIVE_INVALID_FIELD`	400	Format field tidak valid (URL, panjang, dll)	Cek `details.hint`
`WHATSAPP_INTERACTIVE_LIMIT_EXCEEDED`	400	Melebihi batas tombol/section/karakter	Lihat tabel batas di Pesan Interaktif

Resource

Kode	HTTP	Penyebab	Solusi
`RESOURCE_NOT_FOUND`	404	Resource (kontak, percakapan, template) tidak ditemukan	Cek ID yang dikirim
`RESOURCE_ALREADY_EXISTS`	409	Resource dengan identifier yang sama sudah ada (mis. kontak dengan nomor sama)	Pakai endpoint list / update untuk modify resource yang ada

Rate limit & server

Kode	HTTP	Penyebab	Solusi
`SUBSCRIPTION_READ_ONLY`	402	Langganan organisasi tidak aktif. Request baca (`GET`) tetap jalan, request yang mengubah data (`POST`) ditolak	Perpanjang langganan di dashboard
`RATE_LIMIT_EXCEEDED`	429	Melebihi batas request per menit / per hari	Tunggu beberapa saat. Lihat header `X-RateLimit-Reset`.
`SERVER_INTERNAL_ERROR`	500	Error tidak terduga di server Chatera	Coba lagi dengan exponential backoff. Hubungi support kalau berlanjut.
`SERVER_SERVICE_UNAVAILABLE`	503	Layanan sedang maintenance / overload	Coba lagi dalam beberapa menit

Strategi retry

Tidak semua error layak di-retry. Aturan umum:

HTTP	Retry?
`4xx` (kecuali `429`)	Jangan retry — perbaiki request kamu dulu
`429`	Ya, dengan exponential backoff. Hormati header `X-RateLimit-Reset`
`500`, `502`, `503`, `504`	Ya, 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).

Daftar Kode Error

On this page