Hatalar ve idempotency
Durumu değil, hata kodunu esas alın. Ve para harcayan her yeniden denemeyi güvenli hale getirin.
Durumu değil, kodu esas alın
Hatalar { "error": "<code>" } biçiminde döner. Ne yapacağınıza karar vermek için
tek başına durum kodu yeterli değildir; iki farklı 403 birbirinin tersi
çözümler gerektirebilir.
| Durum | Kod | Ne anlama gelir ve ne yapmalısınız |
|---|---|---|
| 401 | invalid_key | Bilinmeyen veya iptal edilmiş anahtar. Yeni bir tane oluşturun; yeniden denemek hiçbir zaman işe yaramaz. |
| 403 | ip_not_allowed | Anahtarın bir IP izin listesi var ve bu adres listede yok. Anahtarda sorun yok; adresi developers.wasync.app/keys sayfasından ekleyin. Anahtarı yenilemeyin. |
| 403 | insufficient_scope | Kimlik bilgisinde bu uç noktanın gerektirdiği kapsam yok. |
| 403 | forbidden_portal_kind | Bir Bitrix24 portalında POST /connections. Oradaki bağlantıları portal yöneticisi oluşturur. |
| 400 | invalid_phone_number | phoneNumber yalnızca rakamlardan oluşmalı, başında + olmamalıdır. |
| 400 | invalid_webhook | URL, herkese açık erişilebilir bir ana makinede HTTPS olmalıdır. |
| 402 | — | Bağlantının lisansı sona ermiş. Bkz. Lisanslar ve deneme. |
| 409 | already_connected | Oturum etkin; eşleştirilecek bir şey yok. |
| 409 | not_supported_for_provider | Bir cloud_api numarasında yalnızca qr için geçerli bir işlem. Kalıcıdır; yeniden denemeyin. |
| 422 | recipient_not_on_whatsapp | WhatsApp, alıcı için bir hesap bulamadı. Numaranın uluslararası biçimde olduğunu (önce ülke kodu, başında sıfır yok) ve kişinin WhatsApp kullandığını kontrol edin. O numara için kalıcıdır; değiştirmeden yeniden denemeyin. |
| 502 | send_failed | WhatsApp, alıcıyla ilgili olmayan bir nedenle (oturum veya sağlayıcı) mesajı iletemedi. Kısa bir bekleme sonrası yeniden deneyin; sürerse bağlantının durumunu kontrol edin. |
| 429 | warmup_limited | Yeni bir qr numarasında saatlik ısınma sınırı. Dakikalar süren bir bekleme uygulayın. |
| 429 | rate_limited | Kötüye kullanım sınırlayıcısı. Varsa Retry-After değerine uyun; buna bakmaksızın varsayılan bir bekleme süresi de tutun. |
| 502 | pairing_code_unavailable | Bir kesinti değil, olağan bir sonuçtur; QR koduna geri dönün. |
Retry-After her 409/429 yanıtında bulunmayabilir; bu yüzden bekleme sürenizi
ona bağlamayın.
POST /connections üzerinde idempotency
Bir bağlantı oluşturmak bir WhatsApp oturumu hazırlar ve ücretli bir kontenjan
tüketir. Zaman aşımına uğrayıp yeniden deneyen bir istemci, aksi halde ikinci
bir bağlantı oluşturur; siz de fark etmeden tek müşteri için iki kontenjan
ödersiniz. İsteğe bağlı Idempotency-Key üstbilgisi bu açığı kapatır. Yalnızca
POST /connections üzerinde desteklenir; kullanmazsanız davranış tamamen eskisi
gibidir.
Anahtar, 255 karaktere kadar herhangi bir opak dizedir; çalışma alanınıza özel bir ad alanında tutulur (aynı dizeyi kullanan iki iş ortağı asla çakışmaz) ve onu kullanan ilk istekten itibaren 24 saat geçerlidir.
201 Created.200 OK ve Idempotency-Replayed: true yanıt üstbilgisi. Bu yanıttaki qr, ilk oluşturmada saklanan kod değil, yeniden alınmış güncel koddur: eşleştirme kodları yaklaşık her 20 saniyede bir yenilenir, bu yüzden eski bir QR tekrar sunulsa taranamazdı. 200'ü hata olarak değil, başarı olarak değerlendirin.400 { "error": "idempotency_key_reuse" }. Karşılaştırma, kanonik gövdenin bir özetiyle yapılır; bu nedenle JSON anahtar sırası önemli değildir.Retry-After: 1 ile birlikte 409 { "error": "idempotency_in_progress" }. Buna uyun ve aynı anahtarla yeniden deneyin.255 karakterden uzun bir anahtar 400 { "error": "idempotency_key_invalid" }
ile reddedilir; asla kısaltılmaz. Boş veya yalnızca boşluktan oluşan bir üstbilgi
yok sayılır. Yanıt gövdesinin yapısı her durumda aynı kalır.
Her müşteri kaydı denemesi için bir anahtar üretin
Çağrıdan hemen önce üretilen ve yalnızca o çağrının yeniden denemelerinde
kullanılan yeni bir UUID (crypto.randomUUID()). Süreç başına, API key başına,
gün başına tek anahtar kullanmayın; sabit bir anahtar da kullanmayın. Anahtar bu
kadar geniş olursa, kaydettiğiniz ikinci müşteriye kendi bağlantısı yerine
birinci müşterinin bağlantısı verilir.
Gönderimlerde idempotency
POST /messages, gövdede (üstbilgide değil) bir idempotencyKey alır. Her
zaman bir tane gönderin: her mantıksal gönderim için bir UUID.
- Herhangi bir hatada veya zaman aşımında aynı anahtarla yeniden deneyin. Yeni bir anahtar, birinin telefonunda ikinci bir gerçek WhatsApp mesajı demektir.
409 in_progressdurumunda aynı anahtarla sorgulamaya devam edin: varsaRetry-Afterdeğerine uyun, yoksa yaklaşık 5 sn bekleyin.- Yavaş bir gönderim, başarısız bir gönderim değildir. HTTP zaman aşımınızı en az 180 sn olarak ayarlayın.