Hız sınırları

API dakikalık sabit pencereli hız sınırı uygular. Sınırlar iki düzeyde sayılır:

• Anahtar düzeyi: her API anahtarının kendi sayacı.
• Hesap düzeyi (2.27.0): hesabınızdaki tüm anahtarların ortak bütçesi. Hesabınızda kaç anahtar olursa olsun toplam bu bütçeyi aşamaz.

Sınırlar işlem türlerine göre ayrı sayaçlarda (kovalarda) tutulur; bir işlem türü diğerinin kotasını tüketmez.

#Kovalar ve varsayılan sınırlar

#Birinci taraf anahtar önceliği

Hesabınıza bağlı bir Veri Merkezi hizmetinin (ör. Sigorta CRM) kurulum anahtarı birinci taraf anahtardır:

• Anahtar sınırı hesap bütçesine eşittir (JSON kovaları 300, medya 150 / dakika).
• Hesap bütçesinin tamamını kullanabilir.

Hesapta birinci taraf anahtar varken diğer anahtarlarınız (kendi entegrasyonlarınız) hesap bütçesinin %40'ını birlikte paylaşır (JSON kovaları 120, medya 60 / dakika). Böylece kendi sistemleriniz hizmetin çalışması için ayrılan payı tüketemez. Hesapta birinci taraf anahtar yoksa pay sınırı uygulanmaz; anahtarlar yalnız kendi sınırlarına ve hesap bütçesine tabidir.

#Eşzamanlı medya indirme (2.28.0)

Dakikalık sınıra ek olarak hesap başına aynı anda en fazla 6 medya indirmesi yapılabilir. Birinci taraf anahtar 6 yuvanın tamamını, diğer anahtarlar birlikte en fazla 2 yuvayı kullanır. HEAD istekleri ve ?meta=1 sayılmaz. Yuva dolunca 429 rate_limited döner: error.scope = concurrency, X-RateLimit-Scope: concurrency, X-Concurrency-Limit ve Retry-After: 2. Bir indirme bitince tekrar deneyin; medyayı aynı anda en fazla 3 istekle indirmeniz önerilir.

Ek sınırlar:

• Şablon senkronu: POST /templates/sync işletme hesabı (WABA) başına dakikada 1 kez. Aşılınca 429 sync_rate_limited.
• Arama izni isteği: aynı kişiye 24 saatte 1, 7 günde 2. Aşılınca 429 permission_request_limited.
• Başarısız kimlik doğrulama: geçersiz anahtarla gelen istekler IP başına dakikada 60.

#Yanıt başlıkları

Her başarılı yanıt kalan hakkınızı iki düzeyde bildirir:

X-RateLimit-Bucket: get
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1791619260
X-RateLimit-Account-Limit: 300
X-RateLimit-Account-Remaining: 288
X-RateLimit-Account-Reset: 1791619260

Bu başlıklar tarayıcıdan yapılan isteklerde de okunabilir (Access-Control-Expose-Headers).

#Sınır aşılınca (429)

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Scope: account_share
Content-Type: application/json

{
  "ok": false,
  "error": {
    "code": "rate_limited",
    "message": "Çok fazla istek (hesaptaki ek anahtarların ortak payı doldu). Lütfen biraz bekleyin.",
    "scope": "account_share",
    "bucket": "media",
    "retry_after": 23
  }
}

Retry-After saniye kadar bekleyip isteği tekrarlayın. Resmî SDK'lar bunu otomatik yapar.

#Geçici yoğunluk (503)

Altyapı geçici olarak yanıt veremezse (ör. veritabanı bağlantısı kısa süre reddedilirse) API 500 yerine 503 döner:

HTTP/1.1 503 Service Unavailable
Retry-After: 5
Content-Type: application/json

{
  "ok": false,
  "error": {
    "code": "temporarily_unavailable",
    "message": "Hizmet geçici olarak yoğun. Retry-After saniye sonra tekrar deneyin.",
    "retry_after": 5
  }
}

Veritabanı kısa sürede art arda bağlantı reddederse API birkaç saniye bağlantı denemeden doğrudan 503 döner (devre kesici); bu sürede önbellekteki anahtar ve medya bilgisiyle medya indirmeleri çalışmayı sürdürür. 503 her zaman güvenle yeniden denenebilir. Kalıcı bir sorun yoksa 500 dönmez; 500 gerçek bir sistem hatasıdır. Bu durumda X-Request-Id değeriyle bize yazın.

#Önerilen yeniden deneme

async function istekGonder(url, secenekler, deneme = 0) {
  const res = await fetch(url, secenekler);
  if ((res.status === 429 || res.status === 503) && deneme < 3) {
    const bekle = Number(res.headers.get('Retry-After') || 5);
    await new Promise((r) => setTimeout(r, bekle * 1000));
    return istekGonder(url, secenekler, deneme + 1);
  }
  return res;
}

import time, requests

def istek_gonder(method, url, deneme=0, **kwargs):
    res = requests.request(method, url, **kwargs)
    if res.status_code in (429, 503) and deneme < 3:
        time.sleep(int(res.headers.get("Retry-After", 5)))
        return istek_gonder(method, url, deneme + 1, **kwargs)
    return res

<?php
function istekGonder(callable $istek, int $deneme = 0): array {
    [$durum, $basliklar, $govde] = $istek();
    if (($durum === 429 || $durum === 503) && $deneme < 3) {
        sleep((int) ($basliklar['retry-after'] ?? 5));
        return istekGonder($istek, $deneme + 1);
    }
    return [$durum, $basliklar, $govde];
}

#Toplu gönderimde öneriler

• Gönderimleri dakikaya yayın. 120/dakika ortalama saniyede 2 isteğe karşılık gelir.
• X-RateLimit-Remaining ya da X-RateLimit-Account-Remaining düştüğünde kritik olmayan işleri erteleyin.
• Okuma işlemlerini (GET) gönderimden ayrı planlayın; ayrı kovalardadır.
• Medya indirmelerini bir kuyruktan, aynı anda en fazla 3 istekle ve dakikada 60'ı aşmayacak şekilde işleyin.
• Aynı hesapta birden fazla entegrasyon çalıştırıyorsanız hesap bütçesini paylaştıklarını unutmayın.
• Meta'nın kendi mesajlaşma limitleri (messaging_limit_tier) ayrıca geçerlidir; GET /numbers ile izleyin.

#Giden webhook teslim sırası

Webhook teslim kuyruğu abonelikler arasında adil paylaştırılır; bir aboneliğin yoğunluğu diğerlerini bekletmez. Aynı abonelik içinde canlı olaylar (message.received, durumlar vb.) geçmiş eşitleme olaylarından (message.history) önce teslim edilir. Her grubun kendi içindeki sırası korunur.