API v2 hataları

Her API v2 hatası gerçek bir HTTP durum koduyla ve aynı JSON yapısıyla gelir. Bu sayfa her code değerini, ne anlama geldiğini ve ne yapmanız gerektiğini listeler. Her hata yanıtı, docs alanında bu sayfadaki koduna bağlantı verir.

Hata nesnesi#

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

Bazı kodlar status, count, used veya limit gibi kendi ayrıntılarını ekler; bunlar kodun yanında listelenir. HTTP 401 yanıtında ayrıca bir WWW-Authenticate: Bearer realm="wbiztool" başlığı bulunur; 429 yanıtlarında (ve 409 idempotency_in_progress yanıtında) Retry-After bulunur.

Kısacası: 4xx, isteğin değiştirilmesi gerektiği (veya 409 ve 429 için beklenmesi gerektiği) anlamına gelir; isteği değiştirmeden yeniden denemek aynı yanıtı verir. 5xx sorunun bizde olduğu anlamına gelir; aynı Idempotency-Key ile daha sonra yeniden deneyin.

Kimlik doğrulama ve sınırlar#

api_v2_not_enabled#

HTTP 403. API v2 bu çalışma alanı için kullanılamıyor. Bunu görüyorsanız bizimle iletişime geçin.

Ne yapmalı: şimdilik API v1 kullanmaya devam edin. Ayarlar → API anahtarları sayfasındaki API v2 anahtarları kartı, sizin için ne zaman açıldığını gösterir.

missing_api_key#

HTTP 401. İstekte Authorization: Bearer … başlığı yok veya başlık boş ya da başka bir şema kullanıyor.

Ne yapmalı: her istekte Authorization: Bearer wbz_live_… (veya wbz_test_…) gönderin. Bkz. Anahtarlar.

invalid_api_key#

HTTP 401. Anahtar bir WbizTool v2 anahtarı değil: yanlış yazılmış, kesik ya da bizim oluşturduğumuz bir anahtar değil.

Ne yapmalı: anahtarı boşluk veya tırnak olmadan yeniden kopyalayın. Bir anahtar oluşturulduktan sonra yeniden gösterilemez; kaybettiyseniz Ayarlar → API anahtarları sayfasında yeni bir anahtar oluşturun.

v1_key_on_v2#

HTTP 401. Anahtar bir API v1 anahtarı (40 karakter, rakamlar ve a–f harfleri). v1 anahtarları yalnızca /api/v1/ üzerinde çalışır.

Ne yapmalı: Ayarlar → API anahtarları sayfasındaki API v2 anahtarları kartında bir v2 anahtarı oluşturun veya API v1 çağırın.

api_key_revoked#

HTTP 401. Anahtar Ayarlar → API anahtarları sayfasında iptal edildi ya da çalışma alanı silindi veya devre dışı bırakıldı.

Ne yapmalı: başka bir anahtar kullanın veya çalışma alanının bir Sahibinden yeni bir anahtar oluşturmasını isteyin.

api_key_expired#

HTTP 401. Anahtarın son kullanma tarihi geçti.

Ne yapmalı: çalışma alanının bir Sahibinden yeni bir anahtar oluşturmasını isteyin ve uygulamanızdaki eski anahtarı değiştirin.

too_many_auth_failures#

HTTP 429. IP adresinizden bir dakika içinde gelen 30'dan fazla istekte yanlış anahtar vardı. Retry-After değeri 60'tır.

Ne yapmalı: durun ve uygulamanızdaki anahtarı düzeltin, ardından bir dakika sonra yeniden deneyin.

demo_account#

HTTP 403. Demo çalışma alanı API'yi kullanamaz.

Ne yapmalı: kendi hesabınız için kaydolun ve anahtarı orada oluşturun.

missing_scope#

HTTP 403. Anahtarda bu isteğin gerektirdiği kapsam yok. Hatadaki required_scope hangisi olduğunu söyler, örneğin messages:send.

Ne yapmalı: bu kapsama sahip bir anahtar oluşturun (mevcut bir anahtara kapsam eklenemez). Bkz. Kapsamlar.

rate_limited#

HTTP 429. Anahtar bu dakika içinde 60'tan fazla veya bugün (UTC) 10.000'den fazla istek yaptı.

Ne yapmalı: Retry-After içindeki saniye kadar bekleyin, ardından yeniden deneyin. İstekleri zamana yayın, çok sayıda alıcı için POST /messages/batch ve sürekli sorgulama yerine webhook'ları kullanın. Bkz. Hız sınırları.

İstek#

not_found#

HTTP 404. Bu adreste hiçbir şey yok: yol yanlış yazılmış veya bir API v2 yolu değil.

Ne yapmalı: yolu referansla karşılaştırın; örneğin /api/v2/message değil, /api/v2/messages.

invalid_json#

HTTP 400. Gövde geçerli bir JSON değil; çoğu zaman sondaki bir virgül veya text içinde kaçış karakteri kullanılmamış bir satır sonu yüzünden.

Ne yapmalı: JSON'u kontrol edin ve dizelerdeki yeni satırları \n olarak yazın. Gövdeyi HTTP kütüphanenizin oluşturmasına izin verin (Python requests'te json=, JavaScript'te JSON.stringify).

unsupported_content_type#

HTTP 415. Gövde bu endpoint'in kabul ettiği biçimde gönderilmemiş: her endpoint application/json kabul eder; tek istisna multipart/form-data kabul eden POST /media endpoint'idir.

Ne yapmalı: Content-Type: application/json ayarlayıp JSON gönderin veya yüklemeyi file alanıyla multipart olarak gönderin.

method_not_allowed#

HTTP 405. Yol var ama bu yöntemle değil; örneğin PUT /messages/9817263.

Ne yapmalı: referansta gösterilen yöntemi kullanın. Bir hatırlatıcıyı değiştirmek PATCH, bir mesajı iptal etmek DELETE ile yapılır.

request_too_large#

HTTP 413. İstek gövdesi çok büyük.

Ne yapmalı: tek istekte daha az veri gönderin; örneğin uzun bir listeyi birkaç toplu gönderime bölün.

validation_failed#

HTTP 400. İsteğin yapısı doğru değil: zorunlu bir alan eksik, bir değerin türü yanlış veya çok uzun, bir alan bilinmiyor ya da limit 1 ile 100 arasında değil. field ilk sorunu belirtir ve message açıklar; errors varsa diğerlerini listeler.

Ne yapmalı: field içinde belirtilen alanı düzeltin. Alan adları snake_case biçimindedir ve bilinmeyen alanlar reddedilir; bu yüzden txt veya phone_number gibi yazım hatalarını kontrol edin.

invalid_cursor#

HTTP 400. cursor bozuk veya bu istektekinden farklı filtreler için oluşturulmuş.

Ne yapmalı: aldığınız next_cursor değerini, ilk sayfadaki filtrelerle birlikte aynen gönderin. Filtreleri değiştirmek için cursor olmadan baştan başlayın.

invalid_idempotency_key#

HTTP 400. Idempotency-Key başlığı boş, 255 karakterden uzun veya yazdırılamayan karakterler içeriyor.

Ne yapmalı: bir UUID veya harf, rakam ve tirelerden oluşan kısa başka bir dize kullanın.

idempotency_key_reused#

HTTP 422. Bu Idempotency-Key son 24 saat içinde farklı bir istekle, yani başka bir yöntem, yol veya gövdeyle zaten kullanıldı.

Ne yapmalı: her yeni istek için yeni bir anahtar kullanın ve bir anahtarı yalnızca tamamen aynı isteği yeniden denemek için tekrar kullanın. Bkz. Idempotency-Key.

idempotency_in_progress#

HTTP 409. Bu Idempotency-Key ile gönderilen ilk istek hâlâ işleniyor. Retry-After değeri 1'dir.

Ne yapmalı: bir saniye bekleyin ve aynı isteği yeniden gönderin: ilk isteğin yanıtını alırsınız.

internal_error#

HTTP 500. Bizim tarafımızda bir sorun oluştu. Bundan haberdar ediliyoruz.

Ne yapmalı: işin iki kez yapılmaması için daha sonra aynı Idempotency-Key ile yeniden deneyin. Sorun devam ederse request_id ile bizimle iletişime geçin.

Mesajlar#

text_required#

HTTP 400. Mesajda text ve media yok veya metin yalnızca boşluklardan oluşuyor. Bir hatırlatıcı için text zorunludur.

Ne yapmalı: text, media veya ikisini birden gönderin.

text_too_long#

HTTP 400. text 3.000 karakterden uzun.

Ne yapmalı: metni kısaltın veya birkaç mesaja bölün.

too_many_recipients#

HTTP 400. Bir toplu gönderimde to içinde 1.000'den fazla alıcı var.

Ne yapmalı: listeyi, her biri kendi Idempotency-Key değerine sahip, en fazla 1.000 alıcılık toplu gönderimlere bölün.

invalid_datetime#

HTTP 400. Bir zaman (send_at, expires_at, since, until) ofsetiyle birlikte ISO 8601 biçiminde değil.

Ne yapmalı: 2026-10-20T09:30:00+05:30 veya 2026-10-20T04:00:00Z gibi yazın. 2026-10-20 09:30 gibi ofseti olmayan bir zaman belirsiz olduğu için reddedilir. Sorgu dizesinde + işaretini %2B olarak yazın.

invalid_phone#

HTTP 422. Bir telefon numarası (to.phone veya numara bağlarken phone) + ile uluslararası biçimde geçerli bir numara değil.

Ne yapmalı: numarayı + ve ülke koduyla yazın, örneğin +919876543210. Boşluklar ve tireler sorun değildir; ülke kodu yerine baştaki bir 0 ise kabul edilmez.

invalid_username#

HTTP 422. to.username bir Telegram kullanıcı adı değil.

Ne yapmalı: @name, bir t.me/name bağlantısı veya tg: ve bir kullanıcı ID'si yazın. Bkz. Alıcılar.

username_needs_telegram#

HTTP 422. Bir Telegram kullanıcı adına yalnızca bir Telegram hesabından gönderim yapılabilir; oysa from bir WhatsApp numarası (veya from olmadan, bağlı tam olarak bir Telegram hesabı yok).

Ne yapmalı: from değerini bir Telegram hesabının ID'si yapın veya bunun yerine bir telefon numarasına gönderin.

contact_not_found#

HTTP 422. Çalışma alanında bu to.contact_id ile bir kişi yok.

Ne yapmalı: ID'yi kontrol edin (örneğin önceki bir mesajın contact_id değeri) veya bunun yerine to.phone adresine gönderin.

media_not_found#

media.media_id ile mesaj gönderirken veya hatırlatıcı oluştururken HTTP 422; GET veya DELETE /media/{id} için HTTP 404. Çalışma alanının Medya klasöründe bu ID ile bir dosya yok veya dosya silinmiş.

Ne yapmalı: ID'yi Dosyaları listeleme ile kontrol edin veya dosyayı yeniden yükleyin.

invalid_media_url#

HTTP 422. media.url herkese açık bir http veya https bağlantısı değil: hatalı biçimlendirilmiş veya özel ya da yerel bir adresi gösteriyor.

Ne yapmalı: internetteki herkesin açabileceği bir bağlantı kullanın veya dosyayı yükleyip media_id ile gönderin.

time_in_past#

HTTP 422. send_at veya expires_at zaten geçmiş.

Ne yapmalı: zamanı ve ofsetini kontrol edin. Hemen göndermek için send_at alanını göndermeyin.

number_not_found#

from (veya bağlarken number_id) bu çalışma alanının bir numarası olmadığında HTTP 422; GET /numbers/{id} için, anahtarın o numarayı kullanamadığı durum dahil, HTTP 404.

Ne yapmalı: doğru id değerini Numaraları listeleme ile alın.

from_required#

HTTP 422. from eksik ve çalışma alanında hiç bağlı numara yok ya da birden fazla var; bu yüzden hangisinin göndereceği belli değil. (Bazı numaralarla sınırlı bir anahtar için: bağlı tek numara, anahtarın numaralarından biri değil.)

Ne yapmalı: gönderimin yapılacağı numaranın id değeriyle from gönderin.

number_not_allowed#

HTTP 403. Anahtar bazı numaralarla sınırlı ve bu istek başka bir numara gerektiriyor: from başka bir numara, bir hatırlatıcı anahtarın numaralarından birini belirtmiyor, bir bağlama isteği numara ekliyor veya başka bir numarayı belirtiyor ya da istek webhook uç noktalarını yönetiyor.

Ne yapmalı: anahtarın numaralarından birini (GET /me içindeki number_ids) veya sınırlı olmayan bir anahtar kullanın.

no_credits#

HTTP 402. Çalışma alanının planında mesajı kalmadı. Toplu gönderimde requested ve remaining, kaç mesaj istendiğini ve kaç mesaj kaldığını söyler.

Ne yapmalı: daha az mesaj gönderin veya bir plan ya da ek mesaj satın alın; ücretli planlar sınırsız mesaj gönderir. Bkz. Mesajlarınız bittiğinde.

account_disabled#

HTTP 403. Çalışma alanı sahibinin hesabı devre dışı, bu yüzden çalışma alanı gönderim yapamaz.

Ne yapmalı: destekle iletişime geçin.

number_daily_cap_reached#

HTTP 429. Gönderen numara son 24 saatte 1.000 mesaj gönderdi (adil kullanım) veya bir toplu gönderim kalan hakka sığmıyor: requested ve room kaç olduğunu söyler.

Ne yapmalı: kalanını daha sonra veya başka bir numaradan gönderin.

message_rejected#

HTTP 422. Mesaj kuyruğa alınamadı; nedenini message söyler. Hiçbir şey kaydedilmedi.

Ne yapmalı: message içinde açıklanan sorunu düzeltin ve yeniden gönderin.

message_not_found#

HTTP 404. Bu anahtar için bu ID ile bir mesaj yok: mesaj mevcut değil, başka bir çalışma alanına ait veya anahtarın kullanamadığı bir numaradan gönderilmiş. Bir test anahtarı yalnızca kendi test mesajlarını görür, canlı bir anahtar ise onları hiçbir zaman görmez.

Ne yapmalı: ID'yi ve mesajı oluşturan anahtarla aynı türde (canlı veya test) bir anahtar kullandığınızı kontrol edin.

not_cancellable#

HTTP 409. Yalnızca bekleyen bir mesaj (queued veya scheduled) iptal edilebilir ve bu mesaj artık beklemiyor. Hatadaki status, mesajın şu anki durumunu söyler; örneğin sent veya cancelled.

Ne yapmalı: iptal edilecek bir şey yok. Gönderilmiş bir mesaj geri alınamaz.

Hatırlatıcılar#

invalid_cron#

HTTP 400. schedule.cron 5 parçalı bir cron ifadesi değil veya hiç gelmeyecek bir zamanı (31 Şubat gibi) tanımlıyor.

Ne yapmalı: dakika, saat, ayın günü, ay ve haftanın gününü yazın; örneğin her pazartesi 09:00 için 0 9 * * 1. Bkz. Zamanlama.

invalid_timezone#

HTTP 400. schedule.timezone bir IANA saat dilimi adı değil.

Ne yapmalı: IST gibi bir kısaltma veya +05:30 gibi bir ofset değil, Asia/Kolkata, Europe/London veya America/New_York gibi bir ad kullanın. Bkz. Saat dilimi referansı.

number_not_connected#

HTTP 422. Hatırlatıcının from değeri bu çalışma alanının bağlı bir numarası değil.

Ne yapmalı: önce numarayı bağlayın, bağlı bir numara seçin veya herhangi bir bağlı numaranın göndermesi için from alanını boş bırakın (null).

reminder_not_found#

HTTP 404. Bu ID ile bir hatırlatıcı yok: mevcut değil, silinmiş veya anahtarın kullanamadığı bir numaradan gönderiyor.

Ne yapmalı: ID'yi Hatırlatıcıları listeleme ile kontrol edin.

Medya#

file_too_large#

HTTP 413. Yüklenen dosya 64 MB'tan büyük.

Ne yapmalı: dosyayı sıkıştırın veya bölün; bir video için çözünürlüğünü düşürün.

unsupported_file_type#

HTTP 415. Dosyanın türü WhatsApp'ta gönderilemiyor. Tür, dosya adının sonundaki uzantıdan okunur.

Ne yapmalı: yükleyebileceğiniz türleri kontrol edin ve uzantıyı adda tutun (price-list değil, price-list.pdf).

storage_full#

HTTP 422. Dosya, planına göre çalışma alanının Medya klasörüne sığmıyor. used ve limit, ne kadarının kullanıldığını ve ne kadarına izin verildiğini bayt cinsinden söyler.

Ne yapmalı: artık ihtiyacınız olmayan dosyaları silin veya daha fazla depolama alanı sunan bir plana geçin.

media_in_use#

HTTP 409. Dosya henüz silinemez: bir şey onu hâlâ gönderecek (bir kampanyanınkiler dahil bekleyen bir mesaj, etkin bir hatırlatıcı veya etkin bir Google Sheets tetikleyicisi). count kaç tane olduğunu söyler.

Ne yapmalı: önce bunları iptal edin veya değiştirin ya da bekleyen mesajlar gönderilene kadar bekleyin.

upload_failed#

HTTP 502. Dosya bizim tarafımızda saklanamadı.

Ne yapmalı: aynı Idempotency-Key ile yeniden deneyin.

Numara kontrolleri#

no_valid_numbers#

HTTP 422. numbers içindeki girişlerin hiçbiri bir telefon numarası değil. skipped kaç giriş olduğunu söyler.

Ne yapmalı: numaraları + ile uluslararası biçimde, her girişte bir numara olacak şekilde gönderin; örneğin +919876543210.

too_many_numbers#

HTTP 422. Kontrolde, tek bir kontrolün içerebileceğinden fazla numara var: istekte 10.000'den fazla giriş veya planın kontrol başına izin verdiğinden fazla numara. count ve limit kaç olduğunu söyler.

Ne yapmalı: listeyi birkaç kontrole bölün. Bkz. Plan sınırları.

number_check_quota_reached#

HTTP 422. Kontrol, planın bu fatura dönemindeki numara kontrolü hakkını aşacak. requested, used ve limit kaç olduğunu söyler.

Ne yapmalı: daha az numara kontrol edin, sonraki fatura dönemini bekleyin veya planınızı yükseltin.

number_check_not_found#

HTTP 404. Çalışma alanında bu ID ile bir numara kontrolü yok.

Ne yapmalı: ID'yi Kontrolleri listeleme ile kontrol edin.

Numaralar#

plan_required#

HTTP 403. Çalışma alanının planı bu isteğin gerektirdiğini içermiyor: numara bağlamak için QR kod API'si, hatırlatıcı oluşturmak, değiştirmek veya sürdürmek için hatırlatıcılar ya da numara kontrolü başlatmak için numara doğrulama.

Ne yapmalı: bir Sahip Fiyatlandırma sayfasından planı yükseltebilir. Zaten var olanları okumak her planda çalışır.

number_limit_reached#

HTTP 403. Planda başka bir numara için yer yok.

Ne yapmalı: mevcut bir numarayı number_id ile yeniden bağlayın, artık kullanmadığınız bir numarayı kaldırın veya planınızı yükseltin.

already_connected#

HTTP 409. Numara zaten bağlı.

Ne yapmalı: yapılacak bir şey yok: bu numaradan gönderim yapabilirsiniz. Numara alma ile kontrol edin.

connect_in_progress#

HTTP 409. Bu numara şu anda bağlanıyor. Hatadaki number_id hangisi olduğunu söyler.

Ne yapmalı: yeniden istemek yerine o numara için GET /numbers/{id} sorgulayın. Taranmadan geçen 10 dakikanın ardından yeniden isteyebilirsiniz.

Webhook'lar#

invalid_webhook_url#

HTTP 422. url herkese açık bir https:// adresi değil: http://, hatalı biçimlendirilmiş veya özel ya da yerel bir adresi gösteriyor.

Ne yapmalı: sunucunuzun internetten yanıt verdiği bir https:// adresi kullanın. Bilgisayarınızda test etmek için size herkese açık bir https:// adresi veren bir tünel hizmeti kullanın.

webhook_limit_reached#

HTTP 403. Çalışma alanında zaten 5 webhook uç noktası var.

Ne yapmalı: artık kullanmadığınız birini kaldırın. Tek bir uç nokta tüm olay türlerini alabilir.

webhook_not_found#

HTTP 404. Bu ID ile bir webhook uç noktası yok: mevcut değil veya kaldırılmış. Durmuş bir uç noktayı test etmek veya gizli anahtarını yenilemek de bu yanıtı verir; okunduğunda active: false gösterir.

Ne yapmalı: ID'yi Uç noktaları listeleme ile kontrol edin. Durmuşsa yeniden ekleyin.

Test modu#

test_mode_unsupported#

HTTP 403. Bir test anahtarı (wbz_test_…) test mesajlarını gönderebilir, okuyabilir ve iptal edebilir, çalışma alanının geri kalanını da okuyabilir, ancak başka hiçbir şeyi değiştiremez: numara bağlamak, hatırlatıcı oluşturmak, değiştirmek veya silmek, medya yüklemek veya silmek, numara kontrolü başlatmak ya da webhook uç noktalarını yönetmek. GET /messages endpoint'inin status filtresi de test anahtarları için desteklenmez.

Ne yapmalı: bu istekler için canlı bir anahtar (wbz_live_…) kullanın. Bkz. Test modu.