Ralat API v2

Setiap ralat API v2 datang dengan kod status HTTP yang sebenar dan bentuk JSON yang sama. Halaman ini menyenaraikan setiap code, maksudnya dan apa yang perlu dilakukan. Setiap respons ralat memaut ke kodnya di sini dalam docs.

Objek ralat#

{
  "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"
  }
}

Sesetengah kod menambah butirannya sendiri, seperti status, count, used atau limit; butiran itu disenaraikan bersama kodnya. Respons dengan HTTP 401 juga mempunyai pengepala WWW-Authenticate: Bearer realm="wbiztool", dan respons dengan 429 (serta 409 idempotency_in_progress) mempunyai Retry-After.

Ringkasnya: 4xx bermaksud permintaan perlu diubah (atau, bagi 409 dan 429, perlu menunggu); mencubanya semula tanpa perubahan memberikan respons yang sama. 5xx bermaksud masalah di pihak kami; cuba semula kemudian, dengan Idempotency-Key yang sama.

Pengesahan identiti dan had#

api_v2_not_enabled#

HTTP 403. API v2 belum tersedia untuk ruang kerja ini. Jika anda melihat ini, hubungi kami.

Apa yang perlu dilakukan: teruskan menggunakan API v1 buat masa ini. Kad Kunci API v2 di Tetapan → Kunci API menunjukkan bila ia dibuka untuk anda.

missing_api_key#

HTTP 401. Permintaan tiada pengepala Authorization: Bearer …, atau pengepala itu kosong atau menggunakan skema lain.

Apa yang perlu dilakukan: hantar Authorization: Bearer wbz_live_… (atau wbz_test_…) pada setiap permintaan. Lihat Kunci.

invalid_api_key#

HTTP 401. Kunci itu bukan kunci v2 WbizTool: salah taip, terpotong, atau bukan kunci yang kami cipta.

Apa yang perlu dilakukan: salin kunci sekali lagi, tanpa ruang atau tanda petik. Kunci tidak boleh dipaparkan semula setelah dicipta; jika anda telah kehilangannya, cipta yang baharu di Tetapan → Kunci API.

v1_key_on_v2#

HTTP 401. Kunci itu ialah kunci API v1 (40 aksara, digit dan a hingga f). Kunci v1 hanya berfungsi pada /api/v1/.

Apa yang perlu dilakukan: cipta kunci v2 dalam kad Kunci API v2 di Tetapan → Kunci API, atau panggil API v1.

api_key_revoked#

HTTP 401. Kunci telah ditarik balik di Tetapan → Kunci API, atau ruang kerjanya telah dipadam atau dinyahdayakan.

Apa yang perlu dilakukan: gunakan kunci lain, atau minta Pemilik ruang kerja mencipta kunci baharu.

api_key_expired#

HTTP 401. Tarikh tamat tempoh kunci telah berlalu.

Apa yang perlu dilakukan: minta Pemilik ruang kerja mencipta kunci baharu, dan gantikan kunci lama dalam aplikasi anda.

too_many_auth_failures#

HTTP 429. Lebih daripada 30 permintaan dalam seminit dari alamat IP anda menggunakan kunci yang salah. Retry-After ialah 60.

Apa yang perlu dilakukan: berhenti dan betulkan kunci dalam aplikasi anda, kemudian cuba lagi selepas seminit.

demo_account#

HTTP 403. Ruang kerja demo tidak boleh menggunakan API.

Apa yang perlu dilakukan: daftar untuk akaun anda sendiri dan cipta kunci di sana.

missing_scope#

HTTP 403. Kunci tiada skop yang diperlukan oleh permintaan ini. required_scope dalam ralat menyatakan skop yang mana, seperti messages:send.

Apa yang perlu dilakukan: cipta kunci dengan skop itu (skop tidak boleh ditambah kepada kunci sedia ada). Lihat Skop.

rate_limited#

HTTP 429. Kunci telah membuat lebih daripada 60 permintaan dalam minit ini, atau lebih daripada 10,000 hari ini (UTC).

Apa yang perlu dilakukan: tunggu selama bilangan saat dalam Retry-After, kemudian cuba lagi. Sebarkan permintaan anda, gunakan POST /messages/batch untuk ramai penerima, dan webhook dan bukannya meninjau berulang kali. Lihat Had kadar.

Permintaan#

not_found#

HTTP 404. Tiada apa-apa di alamat ini: laluan salah taip, atau bukan laluan API v2.

Apa yang perlu dilakukan: semak laluan berbanding rujukan, contohnya /api/v2/messages, bukan /api/v2/message.

invalid_json#

HTTP 400. Badan bukan JSON yang sah, selalunya kerana koma di hujung atau baris baharu yang tidak di-escape dalam text.

Apa yang perlu dilakukan: semak JSON, dan tulis baris baharu dalam rentetan sebagai \n. Biarkan pustaka HTTP anda membina badan (json= dalam Python requests, JSON.stringify dalam JavaScript).

unsupported_content_type#

HTTP 415. Badan tidak dihantar mengikut cara yang diterima oleh endpoint ini: setiap endpoint menerima application/json, kecuali POST /media, yang menerima multipart/form-data.

Apa yang perlu dilakukan: tetapkan Content-Type: application/json dan hantar JSON, atau hantar muat naik sebagai multipart dengan medan file.

method_not_allowed#

HTTP 405. Laluan itu wujud tetapi bukan dengan kaedah ini, seperti PUT /messages/9817263.

Apa yang perlu dilakukan: gunakan kaedah yang ditunjukkan dalam rujukan. Perubahan pada peringatan ialah PATCH; membatalkan mesej ialah DELETE.

request_too_large#

HTTP 413. Badan permintaan terlalu besar.

Apa yang perlu dilakukan: hantar kurang dalam satu permintaan, contohnya pecahkan senarai yang panjang kepada beberapa kelompok.

validation_failed#

HTTP 400. Bentuk permintaan tidak betul: medan wajib tiada, nilai mempunyai jenis yang salah atau terlalu panjang, medan tidak dikenali, atau limit bukan 1 hingga 100. field menamakan masalah pertama dan message menerangkannya; errors menyenaraikan yang lain.

Apa yang perlu dilakukan: betulkan medan yang dinamakan dalam field. Nama medan menggunakan snake_case dan medan yang tidak dikenali ditolak, jadi semak salah taip seperti txt atau phone_number.

invalid_cursor#

HTTP 400. cursor rosak, atau dicipta untuk penapis yang berbeza daripada permintaan ini.

Apa yang perlu dilakukan: hantar next_cursor tepat seperti yang anda terima, dengan penapis yang sama seperti halaman pertama. Untuk menukar penapis, mulakan semula tanpa kursor.

invalid_idempotency_key#

HTTP 400. Pengepala Idempotency-Key kosong, lebih panjang daripada 255 aksara, atau mempunyai aksara yang tidak boleh dicetak.

Apa yang perlu dilakukan: gunakan UUID atau rentetan pendek lain yang terdiri daripada huruf, digit dan sengkang.

idempotency_key_reused#

HTTP 422. Idempotency-Key ini telah digunakan dalam 24 jam yang lalu dengan permintaan yang berbeza: kaedah, laluan atau badan lain.

Apa yang perlu dilakukan: gunakan key baharu bagi setiap permintaan baharu, dan gunakan semula key hanya untuk mencuba semula permintaan yang betul-betul sama. Lihat Idempotency-Key.

idempotency_in_progress#

HTTP 409. Permintaan pertama dengan Idempotency-Key ini masih diproses. Retry-After ialah 1.

Apa yang perlu dilakukan: tunggu sesaat dan hantar permintaan yang sama semula: anda akan mendapat respons permintaan pertama.

internal_error#

HTTP 500. Sesuatu tidak kena di pihak kami. Kami dimaklumkan mengenainya.

Apa yang perlu dilakukan: cuba semula kemudian dengan Idempotency-Key yang sama, supaya kerja tidak dilakukan dua kali. Jika ia terus berlaku, hubungi kami dengan request_id.

Mesej#

text_required#

HTTP 400. Mesej tiada text dan tiada media, atau teksnya hanya ruang. Bagi peringatan, text adalah wajib.

Apa yang perlu dilakukan: hantar text, media atau kedua-duanya.

text_too_long#

HTTP 400. text lebih panjang daripada 3,000 aksara.

Apa yang perlu dilakukan: pendekkannya, atau pecahkannya kepada beberapa mesej.

too_many_recipients#

HTTP 400. Kelompok mempunyai lebih daripada 1,000 penerima dalam to.

Apa yang perlu dilakukan: pecahkan senarai kepada kelompok sehingga 1,000, setiap satu dengan Idempotency-Key sendiri.

invalid_datetime#

HTTP 400. Satu masa (send_at, expires_at, since, until) bukan ISO 8601 dengan ofsetnya.

Apa yang perlu dilakukan: tulisnya seperti 2026-10-20T09:30:00+05:30 atau 2026-10-20T04:00:00Z. Masa tanpa ofset, seperti 2026-10-20 09:30, ditolak kerana ia samar. Dalam rentetan pertanyaan, tulis + sebagai %2B.

invalid_phone#

HTTP 422. Nombor telefon (to.phone, atau phone semasa menyambungkan nombor) bukan nombor yang sah dalam format antarabangsa dengan +.

Apa yang perlu dilakukan: tulisnya dengan + dan kod negara, seperti +919876543210. Ruang dan sengkang dibenarkan; 0 di hadapan sebagai ganti kod negara tidak dibenarkan.

invalid_username#

HTTP 422. to.username bukan nama pengguna Telegram.

Apa yang perlu dilakukan: tulis @name, pautan t.me/name atau tg: diikuti ID pengguna. Lihat Penerima.

username_needs_telegram#

HTTP 422. Nama pengguna Telegram hanya boleh dihantar mesej dari akaun Telegram, dan from ialah nombor WhatsApp (atau, tanpa from, tiada tepat satu akaun Telegram yang disambungkan).

Apa yang perlu dilakukan: tetapkan from kepada ID akaun Telegram, atau hantar ke nombor telefon sebaliknya.

contact_not_found#

HTTP 422. Tiada kenalan dengan to.contact_id ini dalam ruang kerja.

Apa yang perlu dilakukan: semak ID (contohnya contact_id daripada mesej sebelumnya), atau hantar ke to.phone sebaliknya.

media_not_found#

HTTP 422 semasa menghantar mesej atau mencipta peringatan dengan media.media_id; HTTP 404 bagi GET atau DELETE /media/{id}. Tiada fail dengan ID ini dalam Direktori media ruang kerja, atau ia telah dipadam.

Apa yang perlu dilakukan: semak ID dengan Senaraikan fail, atau muat naik fail sekali lagi.

invalid_media_url#

HTTP 422. media.url bukan pautan http atau https awam: formatnya salah, atau ia menghala ke alamat peribadi atau setempat.

Apa yang perlu dilakukan: gunakan pautan yang boleh dibuka oleh sesiapa di internet, atau muat naik fail dan hantarnya dengan media_id.

time_in_past#

HTTP 422. send_at atau expires_at telah berlalu.

Apa yang perlu dilakukan: semak masa dan ofsetnya. Untuk menghantar sekarang, tinggalkan send_at.

number_not_found#

HTTP 422 apabila from (atau number_id semasa menyambung) bukan nombor ruang kerja ini; HTTP 404 bagi GET /numbers/{id}, juga apabila kunci tidak boleh menggunakan nombor itu.

Apa yang perlu dilakukan: dapatkan id yang betul daripada Senaraikan nombor.

from_required#

HTTP 422. from tiada, dan ruang kerja tiada nombor yang disambungkan atau mempunyai lebih daripada satu, jadi tidak jelas yang mana patut menghantar. (Bagi kunci yang dihadkan kepada sebahagian nombor: satu-satunya nombor yang disambungkan bukan salah satu nombor kunci itu.)

Apa yang perlu dilakukan: hantar from dengan id nombor yang akan menghantar.

number_not_allowed#

HTTP 403. Kunci dihadkan kepada sebahagian nombor, dan permintaan ini memerlukan nombor lain: from ialah nombor lain, peringatan tidak menamakan salah satu nombornya, permintaan sambungan menambah nombor atau menamakan nombor lain, atau permintaan mengurus endpoint webhook.

Apa yang perlu dilakukan: gunakan salah satu nombor kunci (number_ids dalam GET /me), atau kunci yang tidak dihadkan.

no_credits#

HTTP 402. Ruang kerja tiada mesej berbaki dalam pelannya. Bagi kelompok, requested dan remaining menyatakan berapa yang diminta dan berapa yang tinggal.

Apa yang perlu dilakukan: hantar lebih sedikit mesej, atau beli pelan atau lebih banyak mesej; pelan berbayar menghantar mesej tanpa had. Lihat Apabila mesej anda habis.

account_disabled#

HTTP 403. Akaun pemilik ruang kerja dinyahdayakan, jadi ruang kerja tidak boleh menghantar.

Apa yang perlu dilakukan: hubungi sokongan.

number_daily_cap_reached#

HTTP 429. Nombor penghantar telah menghantar 1,000 mesej dalam 24 jam yang lalu (penggunaan berpatutan), atau kelompok tidak muat dalam baki ruangnya: requested dan room menyatakan jumlahnya.

Apa yang perlu dilakukan: hantar bakinya kemudian, atau dari nombor lain.

message_rejected#

HTTP 422. Mesej tidak dapat dimasukkan ke dalam baris gilir; message menyatakan sebabnya. Tiada apa yang disimpan.

Apa yang perlu dilakukan: betulkan perkara yang diterangkan dalam message dan hantar semula.

message_not_found#

HTTP 404. Tiada mesej dengan ID ini, untuk kunci ini: ia tidak wujud, milik ruang kerja lain, atau dihantar dari nombor yang tidak boleh digunakan oleh kunci. Kunci ujian hanya melihat mesej ujiannya sendiri, dan kunci langsung tidak sekali-kali melihatnya.

Apa yang perlu dilakukan: semak ID, dan pastikan anda menggunakan jenis kunci yang sama (langsung atau ujian) yang mencipta mesej itu.

not_cancellable#

HTTP 409. Hanya mesej yang menunggu (queued atau scheduled) boleh dibatalkan, dan mesej ini tidak lagi menunggu. status dalam ralat menyatakan statusnya sekarang, seperti sent atau cancelled.

Apa yang perlu dilakukan: tiada apa yang perlu dibatalkan. Mesej yang telah dihantar tidak boleh ditarik semula.

Peringatan#

invalid_cron#

HTTP 400. schedule.cron bukan ungkapan cron 5 bahagian, atau menggambarkan masa yang tidak pernah tiba (seperti 31 Februari).

Apa yang perlu dilakukan: tulis minit, jam, hari dalam bulan, bulan dan hari dalam minggu, seperti 0 9 * * 1 untuk setiap Isnin pada 09:00. Lihat Jadual.

invalid_timezone#

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

Apa yang perlu dilakukan: gunakan nama seperti Asia/Kolkata, Europe/London atau America/New_York, bukan singkatan seperti IST atau ofset seperti +05:30. Lihat rujukan zon waktu.

number_not_connected#

HTTP 422. from peringatan bukan nombor ruang kerja ini yang disambungkan.

Apa yang perlu dilakukan: sambungkan nombor itu dahulu, pilih nombor yang disambungkan, atau tinggalkan from (null) supaya mana-mana nombor yang disambungkan menghantarnya.

reminder_not_found#

HTTP 404. Tiada peringatan dengan ID ini: ia tidak wujud, telah dipadam, atau dihantar dari nombor yang tidak boleh digunakan oleh kunci.

Apa yang perlu dilakukan: semak ID dengan Senaraikan peringatan.

Media#

file_too_large#

HTTP 413. Fail yang dimuat naik lebih besar daripada 64 MB.

Apa yang perlu dilakukan: mampatkan atau pecahkannya; bagi video, kurangkan resolusinya.

unsupported_file_type#

HTTP 415. Jenis fail tidak boleh dihantar di WhatsApp. Jenis dibaca daripada sambungan di hujung nama fail.

Apa yang perlu dilakukan: semak jenis yang boleh anda muat naik, dan kekalkan sambungan dalam nama (price-list.pdf, bukan price-list).

storage_full#

HTTP 422. Fail tidak muat dalam Direktori media ruang kerja untuk pelannya. used dan limit menyatakan berapa banyak yang digunakan dan dibenarkan, dalam bait.

Apa yang perlu dilakukan: padam fail yang tidak lagi anda perlukan, atau beralih ke pelan dengan storan yang lebih besar.

media_in_use#

HTTP 409. Fail belum boleh dipadam: sesuatu masih akan menghantarnya (mesej yang menunggu, termasuk mesej kempen, peringatan yang aktif atau pencetus Google Sheets yang aktif). count menyatakan berapa banyak.

Apa yang perlu dilakukan: batalkan atau ubah semua itu dahulu, atau tunggu sehingga mesej yang menunggu telah dihantar.

upload_failed#

HTTP 502. Fail tidak dapat disimpan di pihak kami.

Apa yang perlu dilakukan: cuba lagi, dengan Idempotency-Key yang sama.

Semakan nombor#

no_valid_numbers#

HTTP 422. Tiada satu pun entri dalam numbers ialah nombor telefon. skipped menyatakan berapa banyak entri yang ada.

Apa yang perlu dilakukan: hantar nombor dalam format antarabangsa dengan +, satu bagi setiap entri, seperti +919876543210.

too_many_numbers#

HTTP 422. Semakan mempunyai lebih banyak nombor daripada yang boleh dimiliki satu semakan: lebih daripada 10,000 entri dalam permintaan, atau lebih banyak nombor daripada yang dibenarkan oleh pelan bagi setiap semakan. count dan limit menyatakan jumlahnya.

Apa yang perlu dilakukan: pecahkan senarai kepada beberapa semakan. Lihat Had pelan.

number_check_quota_reached#

HTTP 422. Semakan akan melebihi kuota semakan nombor pelan untuk tempoh pengebilan ini. requested, used dan limit menyatakan jumlahnya.

Apa yang perlu dilakukan: semak lebih sedikit nombor, tunggu tempoh pengebilan seterusnya, atau naik taraf pelan.

number_check_not_found#

HTTP 404. Tiada semakan nombor dengan ID ini dalam ruang kerja.

Apa yang perlu dilakukan: semak ID dengan Senaraikan semakan.

Nombor#

plan_required#

HTTP 403. Pelan ruang kerja tidak merangkumi apa yang diperlukan oleh permintaan ini: API kod QR untuk menyambungkan nombor, peringatan untuk mencipta, mengubah atau menyambung semula peringatan, atau pengesahan nombor untuk memulakan semakan nombor.

Apa yang perlu dilakukan: Pemilik boleh menaik taraf di Harga. Membaca apa yang sudah ada berfungsi pada mana-mana pelan.

number_limit_reached#

HTTP 403. Pelan tiada ruang untuk nombor lain.

Apa yang perlu dilakukan: sambungkan semula nombor sedia ada dengan number_id, buang nombor yang tidak lagi anda gunakan, atau naik taraf pelan.

already_connected#

HTTP 409. Nombor itu sudah disambungkan.

Apa yang perlu dilakukan: tiada apa yang perlu dilakukan: anda boleh menghantar daripadanya. Semak dengan Dapatkan nombor.

connect_in_progress#

HTTP 409. Nombor ini sedang disambungkan sekarang. number_id dalam ralat menyatakan yang mana.

Apa yang perlu dilakukan: tinjau GET /numbers/{id} untuk nombor itu dan bukannya meminta semula. Selepas 10 minit tanpa imbasan, anda boleh meminta semula.

Webhook#

invalid_webhook_url#

HTTP 422. url bukan alamat https:// awam: ia http://, formatnya salah, atau ia menghala ke alamat peribadi atau setempat.

Apa yang perlu dilakukan: gunakan alamat https:// yang dijawab oleh pelayan anda dari internet. Untuk menguji pada komputer anda, gunakan perkhidmatan terowong yang memberikan anda alamat https:// awam.

webhook_limit_reached#

HTTP 403. Ruang kerja sudah mempunyai 5 endpoint webhook.

Apa yang perlu dilakukan: buang endpoint yang tidak lagi anda gunakan. Satu endpoint boleh menerima setiap jenis peristiwa.

webhook_not_found#

HTTP 404. Tiada endpoint webhook dengan ID ini: ia tidak wujud atau telah dibuang. Menguji atau menukar ganti rahsia endpoint yang telah berhenti juga menjawab ini; membacanya menunjukkan active: false.

Apa yang perlu dilakukan: semak ID dengan Senaraikan endpoint. Jika ia telah berhenti, tambahkannya semula.

Mod ujian#

test_mode_unsupported#

HTTP 403. Kunci ujian (wbz_test_…) boleh menghantar, membaca dan membatalkan mesej ujian serta membaca bahagian lain ruang kerja, tetapi tidak boleh mengubah apa-apa yang lain: menyambungkan nombor, mencipta, mengubah atau memadam peringatan, memuat naik atau memadam media, memulakan semakan nombor, atau mengurus endpoint webhook. Penapis status bagi GET /messages juga tidak disokong untuk kunci ujian.

Apa yang perlu dilakukan: gunakan kunci langsung (wbz_live_…) untuk permintaan ini. Lihat Mod ujian.