Başlarken

Hız limitleri

Limitler iki katmanlıdır: API'nin kendi hız limiti ve mesajlaşma kanalının kendi kısıtları.

API anahtarı başına limit

Her API anahtarının dakikalık bir istek hakkı vardır; varsayılan değer dakikada 60 istektir. Pencere takvim dakikasıdır: hak her dakikanın başında (UTC) yenilenir. Aynı hesaptaki farklı anahtarların hakları birbirinden bağımsızdır.

Yanıt başlıkları

Kimliği doğrulanan her yanıt anlık limit durumunu taşır:

Başlık	Anlamı
`X-RateLimit-Limit`	Anahtarın dakikalık istek hakkı.
`X-RateLimit-Remaining`	Bu dakikada kalan istek hakkı.
`X-RateLimit-Reset`	Mevcut pencerenin bittiği ve hakkın yenileneceği an, ISO 8601 UTC biçiminde (örneğin `2026-10-20T10:01:00.000Z`).
`Retry-After`	Yalnız `429` yanıtlarında: yeniden denemeden önce beklemeniz gereken süre (saniye). Gövdedeki `retry_after` alanı aynı değeri taşır.

Limit aşıldığında 429 ve rate_limit_exceeded döner:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please wait and try again.",
  "retry_after": 45
}

IP adresi başına koruma

API anahtarı kontrol edilmeden önce isteğin geldiği IP adresine de iki sınır uygulanır:

Aynı IP adresinden dakikada 600'den fazla istek gelirse, anahtar fark etmeksizin 429 rate_limit_exceeded döner.
Bir IP adresinden 10 dakika içinde 30 istek 401 alırsa (anahtar eksik, biçimi hatalı, bulunamadı ya da yanlış), o adres 15 dakika boyunca bütün isteklerde 429 too_many_failed_auth alır — geçerli bir anahtar kullansa bile. Bekleme süresi Retry-After başlığında ve retry_after alanındadır.

401 yanıtını tekrar denemeyin

Anahtarı yeniledikten ya da iptal ettikten sonra eski anahtarla çalışmaya devam eden bir entegrasyon kısa sürede kilide takılır ve aynı sunucudan çalışan doğru anahtarlı entegrasyonlarınızı da 15 dakika durdurur. 401 aldığınızda isteği tekrarlamak yerine anahtarı düzeltin.

Kanal tarafındaki kısıtlar

API limitine takılmasanız bile mesajlaşma kanalının kendi kuralları vardır. Kısa sürede çok sayıda kişiye, özellikle daha önce sizinle konuşmamış numaralara mesaj göndermek numaranızın kısıtlanmasına yol açabilir. ZenWapp gönderimleri kuyruklayarak ve aralarına değişken gecikme ekleyerek bu riski azaltır, ancak tempoyu siz de gözetmelisiniz. Hattın gönderim limitini GET /messages/rate-limit ile sorgulayabilirsiniz.

Toplu gönderimde acele etmeyin

POST /messages/broadcast içinde delay_between_messages değerini düşürmek gönderimi hızlandırır ama numaranızın engellenme riskini artırır. Varsayılan değerin altına inmeyin.

429 yanıtını yönetme

Limit hatası aldığınızda isteği hemen tekrarlamayın; Retry-After başlığındaki süre kadar bekleyin. Başlık yoksa üstel geri çekilme uygulayın.

async function sendWithRetry(payload, attempt = 0) {
  const response = await fetch('https://api.zenwapp.com/api/v1/whatsapp/external/messages/send', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.ZENWAPP_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(payload),
  })

  if (response.status !== 429) return response

  // En fazla 5 deneme; her seferinde bekleme süresini ikiye katla.
  if (attempt >= 4) throw new Error('Rate limit: deneme hakkı bitti')

  // Retry-After saniye cinsindendir; yoksa üstel geri çekil.
  const retryAfter = Number(response.headers.get('Retry-After'))
  const waitMs = Number.isFinite(retryAfter) && retryAfter > 0
    ? retryAfter * 1000
    : 2 ** attempt * 1000

  await new Promise((resolve) => setTimeout(resolve, waitMs))
  return sendWithRetry(payload, attempt + 1)
}

Pratik tavsiyeler

Gönderimleri kendi tarafınızda da kuyruklayın; API'ye eşzamanlı yüzlerce istek atmak yerine sabit tempoda akıtın.
İlerlemeyi GET /messages/queue ile izleyin — bekleyen iş sayısı sürekli artıyorsa üretim hızınız tüketim hızını aşıyordur.
Kampanya gönderimlerini POST /messages/broadcast ile yapın; tek tek /messages/send döngüsü kurmayın. Broadcast tempoyu sizin için yönetir.
Yoğun saatler yerine gönderimi zaman dilimine yayın.