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ı.

Yanıt başlıkları

Her yanıt anlık limit durumunu taşır:

Başlık	Anlamı
`X-RateLimit-Limit`	Pencere başına izin verilen istek sayısı.
`X-RateLimit-Remaining`	Mevcut pencerede kalan istek hakkı.
`X-RateLimit-Reset`	Pencerenin sıfırlanacağı an.

Limit aşıldığında 429 ve rate_limit_exceeded döner. Anlık durumu GET /messages/rate-limit ile de sorgulayabilirsiniz.

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.

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; sıfırlanma anına kadar bekleyin ve ü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')

  const reset = Number(response.headers.get('X-RateLimit-Reset'))
  const waitMs = Number.isFinite(reset) && reset > 0
    ? Math.max(reset * 1000 - Date.now(), 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.