Public müşteri API’si auth, yetki, plan ve boyut limitlerini ayrı hata kodları ile döndürür.
İstemci tarafında 401, 403, 413 ve 429 ayrımını ayrı loglamanız önerilir.
Yaygın hata kodları
| Kod | HTTP | Anlam |
|---|---|---|
UNAUTHORIZED | 401 | JWT veya API key bulunamadı |
INVALID_TOKEN | 401 | JWT doğrulanamadı |
INVALID_API_KEY | 401 | API key biçimi veya içeriği geçersiz |
API_KEY_PERMISSION_DENIED | 403 | Anahtar gerekli izne sahip değil |
RATE_LIMIT_EXCEEDED | 429 | İlgili havuzun istek limiti aşıldı |
CONTACT_LIST_LIMIT_REACHED | 403 | Aktif plan kişi listesi limiti dolu |
ASSET_UPLOAD_NOT_ALLOWED | 403 | Aktif plan dosya gönderimini desteklemiyor |
SUBSCRIPTION_REQUIRED | 403 | İşlem için aktif plan veya uygun abonelik gerekli |
FILE_TOO_LARGE | 413 | Dosya istek veya plan limitini aştı |
INVALID_FILE_TYPE | 400 | Yalnızca desteklenen CSV/XLSX veya medya türleri kabul edilir |
CONTACT_LIST_EMPTY | 400 | Geçerli satır bulunamadı |
Örnek hata yanıtı
{
"error": {
"code": "ASSET_UPLOAD_NOT_ALLOWED",
"message": "aktif plan bu işlem için dosya gönderimini desteklemiyor",
"request_id": "3ab4db66-3101-462b-a677-c3c25537d96f"
}
}
Operasyonel limitler
Her alıcı ayrı mesaj olarak sayılır. Tek istek içinde çok alıcı varsa kota buna göre düşer.
Free, Pro ve Growth planlarında toplam kayıtlı liste sayısı plan limitine tabidir.
Dosya yükleme hem genel request limiti hem plan bazlı MIME ve boyut politikası ile kontrol edilir.
Rate limit davranışı
Rate limit, her istek sınıfı için ayrı bir havuz (bucket) üzerinden uygulanır; bir havuzun tükenmesi diğerlerini etkilemez. Limit, kimliği doğrulanmış kullanıcı bazında (anonim isteklerde IP bazında) sayılır. Varsayılan limitler:
| Havuz | Kapsanan uçlar | Limit | Pencere |
|---|---|---|---|
message | Mesaj gönderimi, kampanya ve dosya (message-assets) yükleme | 1000 istek | 1 saat |
otp | POST /v1/messages/otp (ayrı havuz) | 1000 istek | 1 saat |
device | Cihaz yazma uçları (panel) | 100 istek | 5 dakika |
device_read | Cihaz okuma uçları (panel) | 120 istek | 1 dakika |
auth | Kimlik/oturum uçları (panel) | 50 istek | 5 dakika |
Kişi listesi işlemleri (/v1/contact-lists) kendi ayrı havuzuna tabidir; mesaj veya auth
havuzunu tüketmez. Dosya yükleme yüzeyi message havuzuna bağlıdır.
429 yanıt gövdesi
Limit aşıldığında 429 Too Many Requests ve şu gövde döner:
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Çok fazla istek gönderildi. Limit: 1000 / 1h0m0s",
"retry_after": 3600
}
}
retry_after alanı, havuzun sıfırlanması için beklenmesi gereken saniye cinsinden süredir.
Yanıt başlıkları
| Başlık | Anlam |
|---|---|
X-Rate-Limit-Limit | Havuzun pencere başına toplam istek limiti |
X-Rate-Limit-Remaining | Bu pencerede kalan istek sayısı |
X-Rate-Limit-Window | Havuz penceresinin süresi (yalnızca 429 yanıtında) |
Retry-After | Yeniden denemeden önce beklenecek saniye (standart başlık, 429 yanıtında) |
X-Rate-Limit-Remaining her yanıtta döner; 0’a yaklaştığında isteklerinizi yavaşlatın.
429 aldığınızda Retry-After (veya retry_after) kadar bekleyip exponential backoff uygulayın.
Bu dokümanın dışında kalan alanlar
Aşağıdaki alanlar public müşteri API yüzeyinin parçası olmadığı için burada dokümante edilmez:
- Auth ve oturum işlemleri
- API key yönetimi
- Device ve QR uçları
- Billing, abonelik ve fatura
- Profil ve güvenlik ayarları
- Genel usage ve dashboard istatistikleri
Pratik öneriler
request_iddeğerini kendi loglarınıza kaydedin.401ile403durumlarını aynı havuzda toplamayın; biri kimlik, diğeri yetki problemidir.- Import ve upload hatalarında kullanıcıya ham backend hatasını değil kendi alanınıza uygun açıklamayı gösterin.
429sonrası exponential backoff ve tekrar deneme limiti uygulayın.