Error API v2

Setiap error API v2 datang dengan kode status HTTP yang sebenarnya dan bentuk JSON yang sama. Halaman ini mencantumkan setiap code, artinya, dan apa yang harus dilakukan. Setiap respons error menautkan ke kodenya di sini melalui docs.

Objek error#

{
  "error": {
    "code": "not_cancellable",
    "message": "Only a waiting message can be cancelled.",
    "field": null,
    "docs": "https://wbiztool.com/docs/api/v2/errors/#not_cancellable",
    "request_id": "req_4f1c2a9b8e7d6c5b4a392817",
    "status": "sent"
  }
}

Beberapa kode menambahkan detailnya sendiri, seperti status, count, used, atau limit; detail itu dicantumkan bersama kodenya. Respons dengan HTTP 401 juga memiliki header WWW-Authenticate: Bearer realm="wbiztool", dan respons dengan 429 (serta 409 idempotency_in_progress) memiliki Retry-After.

Singkatnya: 4xx berarti request perlu diubah (atau, untuk 409 dan 429, perlu menunggu); mencoba lagi tanpa perubahan memberikan respons yang sama. 5xx berarti masalah di pihak kami; coba lagi nanti, dengan Idempotency-Key yang sama.

Autentikasi dan batas#

api_v2_not_enabled#

HTTP 403. API v2 belum tersedia untuk workspace ini. Jika Anda melihat error ini, hubungi kami.

Yang perlu dilakukan: untuk sementara tetap gunakan API v1. Kartu Kunci API v2 di Pengaturan → Kunci API akan menunjukkan kapan API v2 terbuka untuk Anda.

missing_api_key#

HTTP 401. Request tidak memiliki header Authorization: Bearer …, atau header itu kosong atau memakai skema lain.

Yang perlu dilakukan: kirim Authorization: Bearer wbz_live_… (atau wbz_test_…) di setiap request. Lihat Kunci.

invalid_api_key#

HTTP 401. Kunci bukan kunci v2 WbizTool: salah ketik, terpotong, atau bukan kunci yang kami buat.

Yang perlu dilakukan: salin kunci lagi, tanpa spasi atau tanda kutip. Kunci tidak dapat ditampilkan lagi setelah dibuat; jika kunci hilang, buat yang baru di Pengaturan → Kunci API.

v1_key_on_v2#

HTTP 401. Kunci ini adalah kunci API v1 (40 karakter, berisi digit dan a hingga f). Kunci v1 hanya berfungsi di /api/v1/.

Yang perlu dilakukan: buat kunci v2 di kartu Kunci API v2 pada Pengaturan → Kunci API, atau panggil API v1.

api_key_revoked#

HTTP 401. Kunci telah dicabut di Pengaturan → Kunci API, atau workspace-nya telah dihapus atau dinonaktifkan.

Yang perlu dilakukan: gunakan kunci lain, atau minta Pemilik workspace membuat kunci baru.

api_key_expired#

HTTP 401. Tanggal kedaluwarsa kunci sudah lewat.

Yang perlu dilakukan: minta Pemilik workspace membuat kunci baru, lalu ganti kunci lama di aplikasi Anda.

too_many_auth_failures#

HTTP 429. Lebih dari 30 request dalam satu menit dari alamat IP Anda memakai kunci yang salah. Retry-After bernilai 60.

Yang perlu dilakukan: hentikan dan perbaiki kunci di aplikasi Anda, lalu coba lagi setelah satu menit.

demo_account#

HTTP 403. Workspace demo tidak dapat menggunakan API.

Yang perlu dilakukan: daftar untuk akun Anda sendiri dan buat kunci di sana.

missing_scope#

HTTP 403. Kunci tidak memiliki scope yang dibutuhkan request ini. required_scope di error menyebutkan scope-nya, seperti messages:send.

Yang perlu dilakukan: buat kunci dengan scope tersebut (scope tidak dapat ditambahkan ke kunci yang sudah ada). Lihat Scope.

rate_limited#

HTTP 429. Kunci telah membuat lebih dari 60 request dalam menit ini, atau lebih dari 10.000 hari ini (UTC).

Yang perlu dilakukan: tunggu selama jumlah detik di Retry-After, lalu coba lagi. Sebar request Anda, gunakan POST /messages/batch untuk banyak penerima, dan webhook alih-alih polling. Lihat Batas laju.

Request#

not_found#

HTTP 404. Tidak ada apa pun di alamat ini: path salah ketik, atau bukan path API v2.

Yang perlu dilakukan: periksa path terhadap referensi, misalnya /api/v2/messages, bukan /api/v2/message.

invalid_json#

HTTP 400. Body bukan JSON yang valid, sering kali karena koma di akhir atau baris baru yang tidak di-escape di text.

Yang perlu dilakukan: periksa JSON-nya, dan tulis baris baru di dalam string sebagai \n. Biarkan library HTTP Anda menyusun body (json= di Python requests, JSON.stringify di JavaScript).

unsupported_content_type#

HTTP 415. Body tidak dikirim dengan cara yang diterima endpoint ini: setiap endpoint menerima application/json, kecuali POST /media, yang menerima multipart/form-data.

Yang perlu dilakukan: atur Content-Type: application/json dan kirim JSON, atau kirim unggahan sebagai multipart dengan field file.

method_not_allowed#

HTTP 405. Path-nya ada tetapi tidak dengan method ini, seperti PUT /messages/9817263.

Yang perlu dilakukan: gunakan method yang ditunjukkan referensi. Mengubah pengingat memakai PATCH; membatalkan pesan memakai DELETE.

request_too_large#

HTTP 413. Body request terlalu besar.

Yang perlu dilakukan: kirim lebih sedikit dalam satu request, misalnya pecah daftar panjang menjadi beberapa batch.

validation_failed#

HTTP 400. Bentuk request tidak sesuai: ada field wajib yang tidak ada, nilai dengan jenis yang salah atau terlalu panjang, field yang tidak dikenal, atau limit tidak di antara 1 dan 100. field menyebutkan masalah pertama dan message menjelaskannya; errors mencantumkan masalah lainnya.

Yang perlu dilakukan: perbaiki field yang disebutkan di field. Nama field memakai snake_case dan field yang tidak dikenal ditolak, jadi periksa salah ketik seperti txt atau phone_number.

invalid_cursor#

HTTP 400. cursor rusak, atau dibuat untuk filter yang berbeda dengan request ini.

Yang perlu dilakukan: kirim next_cursor persis seperti yang Anda terima, dengan filter yang sama seperti halaman pertama. Untuk mengubah filter, mulai lagi tanpa cursor.

invalid_idempotency_key#

HTTP 400. Header Idempotency-Key kosong, lebih panjang dari 255 karakter, atau berisi karakter yang tidak dapat dicetak.

Yang perlu dilakukan: gunakan UUID atau string pendek lain yang berisi huruf, digit, dan tanda hubung.

idempotency_key_reused#

HTTP 422. Idempotency-Key ini sudah dipakai dalam 24 jam terakhir dengan request yang berbeda: method, path, atau body lain.

Yang perlu dilakukan: gunakan key baru untuk setiap request baru, dan gunakan ulang key hanya untuk mencoba lagi request yang persis sama. Lihat Idempotency-Key.

idempotency_in_progress#

HTTP 409. Request pertama dengan Idempotency-Key ini masih diproses. Retry-After bernilai 1.

Yang perlu dilakukan: tunggu satu detik dan kirim request yang sama lagi: Anda akan mendapat respons request pertama.

internal_error#

HTTP 500. Terjadi masalah di pihak kami. Kami mendapat pemberitahuan tentangnya.

Yang perlu dilakukan: coba lagi nanti dengan Idempotency-Key yang sama, agar pekerjaan tidak dilakukan dua kali. Jika terus terjadi, hubungi kami dengan menyertakan request_id.

Pesan#

text_required#

HTTP 400. Pesan tidak memiliki text dan tidak memiliki media, atau teksnya hanya berisi spasi. Untuk pengingat, text wajib diisi.

Yang perlu dilakukan: kirim text, media, atau keduanya.

text_too_long#

HTTP 400. text lebih panjang dari 3.000 karakter.

Yang perlu dilakukan: persingkat, atau pecah menjadi beberapa pesan.

too_many_recipients#

HTTP 400. Batch memiliki lebih dari 1.000 penerima di to.

Yang perlu dilakukan: pecah daftar menjadi batch berisi paling banyak 1.000, masing-masing dengan Idempotency-Key sendiri.

invalid_datetime#

HTTP 400. Sebuah waktu (send_at, expires_at, since, until) bukan ISO 8601 dengan offset-nya.

Yang perlu dilakukan: tulis seperti 2026-10-20T09:30:00+05:30 atau 2026-10-20T04:00:00Z. Waktu tanpa offset, seperti 2026-10-20 09:30, ditolak karena ambigu. Di query string, tulis + sebagai %2B.

invalid_phone#

HTTP 422. Nomor telepon (to.phone, atau phone saat menghubungkan nomor) bukan nomor yang valid dalam format internasional dengan +.

Yang perlu dilakukan: tulis dengan + dan kode negara, seperti +919876543210. Spasi dan tanda hubung boleh dipakai; awalan 0 sebagai pengganti kode negara tidak boleh.

invalid_username#

HTTP 422. to.username bukan username Telegram.

Yang perlu dilakukan: tulis @name, tautan t.me/name, atau tg: diikuti ID pengguna. Lihat Penerima.

username_needs_telegram#

HTTP 422. Username Telegram hanya dapat dikirimi dari akun Telegram, sedangkan from adalah nomor WhatsApp (atau, tanpa from, tidak ada tepat satu akun Telegram yang terhubung).

Yang perlu dilakukan: isi from dengan ID akun Telegram, atau kirim ke nomor telepon saja.

contact_not_found#

HTTP 422. Tidak ada kontak dengan to.contact_id ini di workspace.

Yang perlu dilakukan: periksa ID-nya (misalnya contact_id dari pesan sebelumnya), atau kirim ke to.phone saja.

media_not_found#

HTTP 422 saat mengirim pesan atau membuat pengingat dengan media.media_id; HTTP 404 untuk GET atau DELETE /media/{id}. Tidak ada file dengan ID ini di Direktori media workspace, atau file itu sudah dihapus.

Yang perlu dilakukan: periksa ID-nya dengan Daftar file, atau unggah file lagi.

invalid_media_url#

HTTP 422. media.url bukan tautan http atau https publik: formatnya salah, atau mengarah ke alamat privat atau lokal.

Yang perlu dilakukan: gunakan tautan yang dapat dibuka siapa pun di internet, atau unggah file dan kirim dengan media_id.

time_in_past#

HTTP 422. send_at atau expires_at sudah lewat.

Yang perlu dilakukan: periksa waktu dan offset-nya. Untuk mengirim sekarang, jangan kirim send_at.

number_not_found#

HTTP 422 jika from (atau number_id saat menghubungkan) bukan nomor workspace ini; HTTP 404 untuk GET /numbers/{id}, juga jika kunci tidak boleh menggunakan nomor itu.

Yang perlu dilakukan: ambil id yang benar dari Daftar nomor.

from_required#

HTTP 422. from tidak dikirim, dan workspace tidak memiliki nomor yang terhubung atau memiliki lebih dari satu, sehingga tidak jelas nomor mana yang harus mengirim. (Untuk kunci yang dibatasi ke sebagian nomor: satu-satunya nomor yang terhubung bukan salah satu nomor kunci itu.)

Yang perlu dilakukan: kirim from dengan id nomor yang akan mengirim.

number_not_allowed#

HTTP 403. Kunci dibatasi ke sebagian nomor, dan request ini membutuhkan nomor lain: from adalah nomor lain, pengingat tidak menyebutkan salah satu nomornya, request koneksi menambahkan nomor atau menyebutkan nomor lain, atau request mengelola endpoint webhook.

Yang perlu dilakukan: gunakan salah satu nomor kunci (number_ids di GET /me), atau kunci yang tidak dibatasi.

no_credits#

HTTP 402. Pesan di paket workspace sudah habis. Untuk batch, requested dan remaining menunjukkan berapa yang diminta dan berapa yang tersisa.

Yang perlu dilakukan: kirim lebih sedikit pesan, atau beli paket atau tambahan pesan; paket berbayar mengirim pesan tanpa batas. Lihat Saat pesan Anda habis.

account_disabled#

HTTP 403. Akun pemilik workspace dinonaktifkan, sehingga workspace tidak dapat mengirim.

Yang perlu dilakukan: hubungi dukungan.

number_daily_cap_reached#

HTTP 429. Nomor pengirim sudah mengirim 1.000 pesan dalam 24 jam terakhir (penggunaan wajar), atau batch tidak muat dalam sisa kapasitasnya: requested dan room menunjukkan jumlahnya.

Yang perlu dilakukan: kirim sisanya nanti, atau dari nomor lain.

message_rejected#

HTTP 422. Pesan tidak dapat dimasukkan ke antrean; message menyebutkan alasannya. Tidak ada yang disimpan.

Yang perlu dilakukan: perbaiki hal yang dijelaskan di message dan kirim lagi.

message_not_found#

HTTP 404. Tidak ada pesan dengan ID ini untuk kunci ini: pesan tidak ada, milik workspace lain, atau dikirim dari nomor yang tidak boleh digunakan oleh kunci. Kunci uji hanya melihat pesan ujinya sendiri, dan kunci live tidak pernah melihatnya.

Yang perlu dilakukan: periksa ID-nya, dan pastikan Anda memakai jenis kunci yang sama (live atau uji) dengan yang membuat pesan.

not_cancellable#

HTTP 409. Hanya pesan yang menunggu (queued atau scheduled) yang dapat dibatalkan, dan pesan ini sudah tidak menunggu. status di error menyebutkan statusnya sekarang, seperti sent atau cancelled.

Yang perlu dilakukan: tidak ada yang perlu dibatalkan. Pesan yang sudah terkirim tidak dapat ditarik kembali.

Pengingat#

invalid_cron#

HTTP 400. schedule.cron bukan ekspresi cron 5 bagian, atau menggambarkan waktu yang tidak pernah datang (seperti 31 Februari).

Yang perlu dilakukan: tulis menit, jam, tanggal, bulan, dan hari dalam seminggu, seperti 0 9 * * 1 untuk setiap Senin pukul 09.00. Lihat Jadwal.

invalid_timezone#

HTTP 400. schedule.timezone bukan nama zona waktu IANA.

Yang perlu dilakukan: gunakan nama seperti Asia/Kolkata, Europe/London, atau America/New_York, bukan singkatan seperti IST atau offset seperti +05:30. Lihat referensi zona waktu.

number_not_connected#

HTTP 422. from pengingat bukan nomor terhubung di workspace ini.

Yang perlu dilakukan: hubungkan nomornya terlebih dahulu, pilih nomor yang terhubung, atau jangan kirim from (null) agar nomor terhubung mana pun yang mengirimnya.

reminder_not_found#

HTTP 404. Tidak ada pengingat dengan ID ini: pengingat tidak ada, sudah dihapus, atau dikirim dari nomor yang tidak boleh digunakan oleh kunci.

Yang perlu dilakukan: periksa ID-nya dengan Daftar pengingat.

Media#

file_too_large#

HTTP 413. File yang diunggah lebih besar dari 64 MB.

Yang perlu dilakukan: kompres atau pecah file; untuk video, turunkan resolusinya.

unsupported_file_type#

HTTP 415. Jenis file tidak dapat dikirim di WhatsApp. Jenis file dibaca dari ekstensi di akhir nama file.

Yang perlu dilakukan: periksa jenis file yang dapat Anda unggah, dan pertahankan ekstensi di nama file (price-list.pdf, bukan price-list).

storage_full#

HTTP 422. File tidak muat di Direktori media workspace untuk paketnya. used dan limit menunjukkan ruang yang terpakai dan yang diizinkan, dalam byte.

Yang perlu dilakukan: hapus file yang tidak lagi Anda perlukan, atau pindah ke paket dengan penyimpanan lebih besar.

media_in_use#

HTTP 409. File belum dapat dihapus: masih ada yang akan mengirimnya (pesan yang menunggu, termasuk pesan kampanye, pengingat aktif, atau pemicu Google Sheets yang aktif). count menunjukkan jumlahnya.

Yang perlu dilakukan: batalkan atau ubah semua itu terlebih dahulu, atau tunggu sampai pesan yang menunggu terkirim.

upload_failed#

HTTP 502. File tidak dapat disimpan di pihak kami.

Yang perlu dilakukan: coba lagi, dengan Idempotency-Key yang sama.

Pemeriksaan nomor#

no_valid_numbers#

HTTP 422. Tidak ada entri di numbers yang berupa nomor telepon. skipped menunjukkan jumlah entrinya.

Yang perlu dilakukan: kirim nomor dalam format internasional dengan +, satu per entri, seperti +919876543210.

too_many_numbers#

HTTP 422. Pemeriksaan berisi lebih banyak nomor daripada yang boleh dimiliki satu pemeriksaan: lebih dari 10.000 entri dalam request, atau lebih banyak nomor daripada yang diizinkan paket per pemeriksaan. count dan limit menunjukkan jumlahnya.

Yang perlu dilakukan: pecah daftar menjadi beberapa pemeriksaan. Lihat Batas paket.

number_check_quota_reached#

HTTP 422. Pemeriksaan akan melewati jatah pemeriksaan nomor paket untuk periode penagihan ini. requested, used, dan limit menunjukkan jumlahnya.

Yang perlu dilakukan: periksa lebih sedikit nomor, tunggu periode penagihan berikutnya, atau tingkatkan paket.

number_check_not_found#

HTTP 404. Tidak ada pemeriksaan nomor dengan ID ini di workspace.

Yang perlu dilakukan: periksa ID-nya dengan Daftar pemeriksaan.

Nomor#

plan_required#

HTTP 403. Paket workspace tidak mencakup apa yang dibutuhkan request ini: API kode QR untuk menghubungkan nomor, pengingat untuk membuat, mengubah, atau melanjutkan pengingat, atau verifikasi nomor untuk memulai pemeriksaan nomor.

Yang perlu dilakukan: Pemilik dapat meningkatkan paket di halaman Harga. Membaca data yang sudah ada berfungsi di paket apa pun.

number_limit_reached#

HTTP 403. Paket tidak memiliki ruang untuk nomor lain.

Yang perlu dilakukan: hubungkan kembali nomor yang sudah ada dengan number_id, hapus nomor yang tidak lagi Anda gunakan, atau tingkatkan paket.

already_connected#

HTTP 409. Nomor sudah terhubung.

Yang perlu dilakukan: tidak ada yang perlu dilakukan: Anda dapat mengirim dari nomor itu. Periksa dengan Mengambil nomor.

connect_in_progress#

HTTP 409. Nomor ini sedang dihubungkan saat ini. number_id di error menyebutkan nomor yang mana.

Yang perlu dilakukan: lakukan polling GET /numbers/{id} untuk nomor itu alih-alih meminta lagi. Setelah 10 menit tanpa pemindaian, Anda dapat meminta lagi.

Webhook#

invalid_webhook_url#

HTTP 422. url bukan alamat https:// publik: alamatnya http://, formatnya salah, atau mengarah ke alamat privat atau lokal.

Yang perlu dilakukan: gunakan alamat https:// yang dijawab server Anda dari internet. Untuk menguji di komputer Anda, gunakan layanan tunnel yang memberi Anda alamat https:// publik.

webhook_limit_reached#

HTTP 403. Workspace sudah memiliki 5 endpoint webhook.

Yang perlu dilakukan: hapus endpoint yang tidak lagi Anda gunakan. Satu endpoint dapat menerima semua jenis peristiwa.

webhook_not_found#

HTTP 404. Tidak ada endpoint webhook dengan ID ini: endpoint tidak ada atau sudah dihapus. Menguji atau merotasi rahasia endpoint yang sudah berhenti juga dijawab dengan error ini; membacanya menampilkan active: false.

Yang perlu dilakukan: periksa ID-nya dengan Daftar endpoint. Jika endpoint sudah berhenti, tambahkan lagi.

Mode uji#

test_mode_unsupported#

HTTP 403. Kunci uji (wbz_test_…) dapat mengirim, membaca, dan membatalkan pesan uji serta membaca bagian lain workspace, tetapi tidak dapat mengubah hal lain: menghubungkan nomor, membuat, mengubah, atau menghapus pengingat, mengunggah atau menghapus media, memulai pemeriksaan nomor, atau mengelola endpoint webhook. Filter status di GET /messages juga tidak didukung untuk kunci uji.

Yang perlu dilakukan: gunakan kunci live (wbz_live_…) untuk request ini. Lihat Mode uji.