Error & Solusi

Error itu bagian dari hidup, apalagi hidup developer. Semua error dari Zate bentuknya sama:

{
  "statusCode": 404,
  "message": "session not found"
}

Cocokin statusCode dan message yang kamu dapet sama tabel di bawah, terus ikutin solusinya.

400: Request-nya Kurang Pas

message	Artinya	Solusi
invalid header	Header id atau session-id nggak dikirim.	Kirim dua header itu di semua endpoint selain POST /session dan link media.
invalid phone, username, user, group or channel	Kirim Pesan tanpa tujuan.	Isi salah satu dari phone, username, user, group, atau channel.
invalid phone, username, user or group	Kirim Typing tanpa tujuan.	Isi salah satu dari phone, username, user, atau group.
invalid receiver	Nomor HP kurang dari 8 digit setelah dirapihin.	Cek lagi formatnya di Konsep Dasar.
invalid chat	Username-nya nggak valid, misalnya ada spasi atau nggak diawali huruf.	Cek lagi penulisannya. Boleh pakai @ atau link t.me.
chat not found	Username nggak ada, atau ID-nya belum dikenal akun kamu.	Pakai username, atau ambil ID yang bener dari Ambil Group, Ambil Channel, atau Ambil Member Group.
phone is not on telegram or hidden by its privacy settings	Nomornya nggak punya Telegram, atau pemiliknya nyembunyiin diri dari pencarian nomor.	Pakai username atau ID user.
channel not found	ID atau username-nya ada, tapi bukan channel (misalnya grup), atau kamu belum gabung ke channel itu.	Gabung dulu dari Telegram, atau ambil ID channel dari Ambil Channel.
group not found	ID atau username-nya ada, tapi bukan grup (misalnya channel), atau kamu belum gabung ke grup itu.	Gabung dulu dari Telegram, atau ambil ID grup dari Ambil Group.
password is not required	Kirim Password dipanggil padahal sesi lagi nggak nunggu password.	Cek isPasswordRequired di Ambil Session dulu.
invalid password	Password verifikasi dua langkah salah.	Coba lagi. Petunjuknya ada di passwordHint.
url and token must be both filled, or both empty to turn the webhook off	Atur Webhook cuma diisi salah satu.	Isi dua-duanya, atau kosongin dua-duanya buat matiin webhook.
url must be an http or https url	URL webhook nggak valid.	Pakai URL lengkap yang diawali http:// atau https://.
type must be one of the following values: ...	Nilai type nggak dikenal.	Pakai salah satu nilai yang disebut di pesan error-nya.
text should not be empty	type diisi text, tapi text kosong.	Isi kolom text.
image should not be empty (juga video, audio, dst.)	Objek media untuk type itu nggak dikirim.	Kirim objeknya, misalnya image buat type: "image".
image.url should not be empty, video.duration must be a positive number, dst.	Ada kolom wajib di dalam objek yang kosong atau salah.	Cek tabel objek di Kirim Pesan.
parseMode must be one of the following values: markdown, html	Nilai parseMode nggak dikenal.	Pakai markdown, html, atau jangan dikirim.
privacy must be one of the following values: ...	Nilai privacy di Kirim Status nggak dikenal.	Pakai contacts, everyone, atau close_friends.
groupId should not be empty / channelId should not be empty	Query parameter wajib nggak dikirim.	Tambahin parameternya ke URL.

404: Nggak Ketemu

message	Artinya	Solusi
session not found	id atau session-id salah, atau sesinya udah dihapus.	Cek lagi dua header itu. Kalau udah bener, berarti sesinya udah hilang, jadi bikin sesi baru.
media not found	Link media diubah-ubah, atau pesannya udah dihapus.	Ambil link yang baru dari Ambil Pesan Channel atau webhook.

Sesi bisa hilang karena beberapa hal: QR nggak di-scan dalam 3 menit, sesi terputus lebih dari 30 menit, atau kamu sendiri yang hapus. Detailnya ada di Siklus Hidup Sesi.

500: Ada Masalah Waktu Diproses

message	Artinya	Solusi
session not connected	Sesinya ada, tapi lagi nggak nyambung ke Telegram.	Cek Ambil Session. Kalau qrcode terisi, scan lagi. Kalau isPasswordRequired: true, kirim password. Kalau dua-duanya kosong, tunggu sebentar karena Zate lagi nyambung ulang.
session not found	Sesinya ada di database tapi belum aktif di server, misalnya karena server baru restart.	Tunggu beberapa detik, terus coba lagi. Kalau tetap gagal, reset atau bikin sesi baru.
error parser file from url ...	Media gagal diunduh dari URL yang kamu kasih.	Pastikan URL-nya publik, langsung ke file, dan servernya cepat jawab.
send timeout after 240s	Proses kirim lebih dari 4 menit.	Pakai file yang lebih kecil atau server file yang lebih cepat.
error compress image: ...	Gambar gagal diproses.	Pastikan URL-nya beneran gambar yang valid (JPG, PNG, atau WebP).
400: NAMA_ERROR (caused by ...) dan sejenisnya	Error langsung dari Telegram.	Lihat Error dari Telegram di bawah.
internal server error atau pesan lainnya	Ada yang nggak beres di server.	Coba lagi beberapa saat. Kalau masih, kabarin kita ya.

503: Telegram Minta Nunggu

Cuma muncul di Ambil Media. Response-nya bawa header Retry-After berisi jumlah detik yang perlu kamu tunggu.

message	Artinya	Solusi
telegram asked to wait 120s	Telegram lagi ngebatasin request media akun kamu.	Tunggu sesuai Retry-After, terus buka lagi.
telegram did not answer the media request in time	Telegram nggak jawab dalam 30 detik.	Coba lagi sebentar lagi.

Error dari Telegram

Kalau Telegram yang nolak, pesannya diterusin apa adanya dengan format kode: NAMA_ERROR (caused by request), contohnya:

{
  "statusCode": 500,
  "message": "403: CHAT_WRITE_FORBIDDEN (caused by messages.SendMessage)"
}

Yang paling sering ketemu:

Error	Artinya
PEER_FLOOD	Akun kamu dibatasi karena dianggap spam. Cek @SpamBot dan baca lagi Sebelum Mulai.
A wait of N seconds is required	Kebanyakan request, Telegram minta nunggu N detik. Jeda di bawah semenit ditunggu otomatis, yang lebih lama dikembaliin sebagai error.
CHAT_WRITE_FORBIDDEN	Kamu nggak boleh kirim pesan di grup atau channel itu.
CHAT_ADMIN_REQUIRED	Butuh hak admin, misalnya posting ke channel orang lain atau lihat anggota grup yang disembunyiin.
USER_IS_BLOCKED / YOU_BLOCKED_USER	Kamu diblokir orang itu, atau kamu yang ngeblokir dia.
PRIVACY_PREMIUM_REQUIRED	Orangnya cuma nerima pesan dari kontak atau pengguna Telegram Premium.
MESSAGE_TOO_LONG / MEDIA_CAPTION_TOO_LONG	Teks atau caption kepanjangan.
SLOWMODE_WAIT_N	Grupnya pakai slow mode, tunggu N detik sebelum kirim lagi.
STORIES_TOO_MUCH	Batas story akun kamu udah kepakai.

Pertanyaan yang Sering Muncul

qrcode kosong terus, gimana dong?

Di beberapa detik pertama setelah Buat Session atau Reset Session, itu wajar. Panggil Ambil Session tiap 2–3 detik. Kalau isPasswordRequired jadi true, berarti QR-nya udah di-scan dan tinggal kirim password.

Telegram bilang QR-nya kedaluwarsa pas di-scan.

QR-nya ganti kira-kira tiap 30 detik, jadi kemungkinan kamu nge-scan QR yang lama. Ambil QR terbaru dari Ambil Session, terus scan lagi.

Udah scan QR, tapi isConnected masih false.

Cek isPasswordRequired. Kalau true, akun kamu pakai verifikasi dua langkah dan Zate lagi nunggu password. Kalau false, tunggu beberapa detik terus cek lagi.

Kirim ke nomor HP gagal terus.

Di Telegram, orang bisa nyembunyiin diri dari pencarian nomor, dan banyak yang nyalain itu. Pakai username atau user (ID) aja, jauh lebih bisa diandelin.

Tiba-tiba harus scan QR lagi, padahal nggak ngapa-ngapain.

Biasanya karena perangkat Zate dikeluarin dari Settings → Devices, atau Telegram mutusin sesinya. Zate langsung nyiapin QR baru, tapi QR itu cuma berlaku 3 menit. Kalau nggak keburu, sesinya dihapus dan kamu perlu bikin sesi baru.

Webhook nggak masuk-masuk.

Cek satu-satu: URL-nya bisa diakses dari internet, server kamu ngecek x-token dengan token yang sama, dan jawabannya 2xx dalam 10 detik. Inget juga, webhook cuma ngirim event chat pribadi, dan pesan sebelum webhook dipasang nggak ikut dikirim. Detailnya di Terima Pesan.