Error
Setiap respons API Kirisan berformat JSON. Panggilan berhasil menyertakan "status": true. Kegagalan menyertakan "status": false dan "reason" yang mudah dibaca ketika seluruh permintaan gagal sebelum pengiriman ke channel.
Kode status HTTP
| Status | Kapan terjadi |
|---|---|
200 | Permintaan terurai — periksa "status" di body (send dapat mengembalikan 200 dengan "status": false dan detail channel) |
400 | JSON tidak valid, field hilang, atau error validasi |
401 | Bearer token hilang atau tidak valid |
403 | Bearer token valid tetapi channel key bukan milik akun Anda |
503 | Layanan sementara tidak tersedia |
POST /v1/send biasanya mengembalikan HTTP 200 meskipun pengiriman gagal — baca "status" dan "channels".
reason tingkat atas
Ini muncul di root respons ketika permintaan tidak pernah sampai ke pengiriman, atau ketika setiap channel gagal secara blocking:
| Reason (contoh) | Arti |
|---|---|
missing api token / invalid api token | Perbaiki Authorization: Bearer … — lihat Authentication |
invalid JSON | Body bukan JSON valid |
No channels configured | keys kosong — sertakan minimal satu token channel |
content required | Tidak ada objek content dengan minimal satu channel |
no sendable channels: content requires a matching key | Anda mengatur content.whatsapp tetapi tidak menyertakan keys.whatsapp, atau sejenisnya |
Invalid schedule: the time is in the past. | context.timing.schedule harus timestamp Unix di masa depan |
whatsapp key does not belong to this account | Token channel milik pengguna lain (403) |
Error validasi dari body pesan juga dikembalikan sebagai "reason" tingkat atas sebelum send — misalnya email inline message requires subject atau waba message type must be text, interactive, image, video, or document.
Error per channel (channels)
Pada POST /v1/send, setiap channel yang Anda coba punya objek sendiri di bawah "channels":
{
"status": false,
"channels": {
"whatsapp": {
"status": false,
"reason": "template is not approved for sending",
"processing_time": "142ms"
},
"email": {
"status": true,
"processing_time": "891ms"
}
}
}| Field | Arti |
|---|---|
status | true jika channel tersebut terkirim (atau dijadwalkan) |
reason | Ada jika status adalah false — kuota, target hilang, template tidak aktif, error provider, dll. Untuk email, error SMTP/transport diringkas menjadi kalimat singkat yang mudah dibaca (misalnya Recipient address does not exist). Teks mentah provider hanya disimpan di log internal. Kegagalan email yang tidak dikenali mengembalikan Email could not be delivered. Pesan kuota seperti insufficient quota dan paid plan expired dikembalikan apa adanya. |
detail | Payload provider tambahan pada beberapa channel (WhatsApp, Telegram, WABA) |
processing_time | Lama panggilan ke provider |
scheduled | true ketika pesan diantre untuk context.timing.schedule |
fallback | true ketika channel ini mengirim sebagai bagian dari tier fallback |
Ketika satu channel gagal dan yang lain berhasil (misalnya WhatsApp gagal, fallback email berhasil), "status" tingkat atas mungkin tetap true jika ada channel yang terkirim.
Error template saat send
Ketika content.<channel>.template menunjuk ke template dashboard yang tidak bisa dikirim:
| Reason | Arti |
|---|---|
template is not approved for sending | Template masih menunggu review atau ditolak |
template is inactive | Template ada tetapi dimatikan di dashboard |
WhatsApp template not found | ID salah, channel salah, atau template milik akun lain |
Buat template di Channel → channel → Templates dan pastikan status Approved dan Active sebelum mereferensikan ID-nya saat send.
Error email
Alasan ini muncul di "channels.email.reason" (atau di root jika email adalah satu-satunya channel yang gagal):
| Reason | Arti | Yang dilakukan |
|---|---|---|
rate_limited | Anda mengirim lebih dari 2 permintaan per detik untuk email marketing atau tanpa template pada domain yang sama. Respons bisa menyertakan retry_after (detik). | Tunggu, lalu kirim lagi. Template transactional tidak memakai batas ini. |
queue_full | Terlalu banyak email marketing atau tanpa template masih menunggu untuk domain ini. | Tunggu beberapa terkirim, lalu coba lagi. |
email_lane_blocked | Jenis email itu (transactional, marketing, atau raw) sedang diblokir di domain. | Buka Channel → Email → Domains, baca label di bawah Sending health, lalu Acknowledge. |
email_domain_suspended | Kesehatan domain menjeda jenis email itu. | Buka Channel → Email → Domains. Badge bisa menampilkan Suspended until …. Tunggu atau acknowledge sesuai yang ditampilkan. |
not_in_email_pool | Template marketing ke alamat yang belum pernah menerima email dari domain ini. | Kirim dulu transactional atau email tanpa template ke alamat itu, atau pakai alamat yang sudah pernah Anda kirimi. |
email inline message requires subject | Pesan tanpa template tidak punya subject. | Tambahkan subject. |
email inline message requires message or html | Pesan tanpa template tidak punya isi. | Tambahkan message dan/atau html. |
email inline message type must be text | message.type bukan text. | Set type ke "text". |
Error SMTP (gagal kirim ke provider)
Saat email service menolak kiriman ke Gmail/Outlook/Yahoo, channels.email.reason memakai kode stabil (bukan teks SMTP mentah). Detail SMTP penuh ada di log Kirisan (admin).
| Reason | Arti | Yang dilakukan |
|---|---|---|
recipient_not_found | Alamat penerima tidak ada atau invalid (hard bounce). | Hapus atau perbaiki alamat; alamat ini di-suppress permanen. |
recipient_temp_unavailable | Kotak penuh atau penerima sementara tidak bisa menerima (soft bounce). | Coba lagi nanti; alamat di-suppress 24 jam (3× → permanen). |
delivery_temporarily_unavailable | Penundaan sementara (greylist, server sibuk, timeout). | Respons bisa menyertakan retryable: true. Coba lagi nanti. |
rate_limited_by_provider | Provider membatasi pengirim (IP/domain/reputasi), bukan alamat penerima. | Perlambat volume; perbaiki auth/warmup. Jangan hapus alamat dari list. |
blocked_by_provider | IP/domain masuk block list provider (mis. Outlook S3150). | Perbaiki reputasi; minta delist jika perlu. Alamat penerima tetap valid. |
policy_rejected | Auth/policy (SPF, DMARC, konten, Outlook SC-/DY-/OU-). | Perbaiki DNS auth atau konten. |
message_rejected | Ukuran, format, atau syntax pesan ditolak. | Perkecil lampiran atau perbaiki format. |
rate_limited (2 req/detik per domain) berbeda dari rate_limited_by_provider (batas Gmail/Outlook/Yahoo).
Lihat Send API untuk tiga jenis email, dan Mengirim pesan jika kiriman tertolak atau tertahan.
Terkait
- Authentication — token dan channel key
- Send API — bentuk permintaan, tiga jenis email, dan perilaku fallback
- Send messages — tier fallback yang sama di dashboard
- Mengirim pesan — queued, rate limit, dan domain Blocked