Başlarken

Hata kodları

Hata yanıtları tutarlı bir yapı kullanır: makine tarafından okunabilir bir error kodu ve insan tarafından okunabilir bir message.

{
  "error": "validation_error",
  "message": "Missing required field: to"
}

Koda göre dallanın, metne göre değil

message alanı iyileştirme amacıyla değişebilir. Uygulama mantığınızı her zaman error koduna ve HTTP durumuna dayandırın.

Standart kodlar

HTTP	error	Anlamı	Ne yapmalı
`400`	`validation_error`	Zorunlu alan eksik veya biçim hatalı.	İsteği düzeltin. Tekrar denemek aynı sonucu verir.
`400`	`account_not_connected`	Kanal hesabı bağlı değil.	Panelden kanalı yeniden bağlayın; bekleyip tekrar deneyin.
`401`	`invalid_api_key`	Anahtar eksik veya geçersiz.	Anahtarı kontrol edin. Tekrar denemeyin.
`403`	`forbidden`	Anahtarın bu uç için yetkisi yok.	Panelden anahtara gerekli yetkiyi ekleyin.
`404`	`not_found`	Kaynak yok ya da bu hesaba ait değil.	Kimliği doğrulayın. Tekrar denemeyin.
`429`	`rate_limit_exceeded`	Anahtarın dakikalık hakkı ya da IP adresinin dakikalık tavanı aşıldı.	`Retry-After` başlığındaki saniye kadar bekleyin, sonra yeniden deneyin.
`429`	`too_many_failed_auth`	Bu IP adresinden kısa sürede çok sayıda geçersiz anahtarlı istek geldi; adres 15 dakika kilitlendi.	Önce anahtarı düzeltin; `Retry-After` süresi dolmadan yapılan her istek reddedilir.
`500`	`internal_error`	Sunucu tarafında beklenmeyen hata.	Üstel geri çekilme ile en fazla birkaç kez deneyin.
`504`	`send_timeout`	`sync: true` modunda gönderim zaman aşımına uğradı.	Körü körüne tekrar göndermeyin — çift mesaj riski var. Webhook ile doğrulayın.

Uca özel kodlar

Bazı uçlar kendi bağlamlarına özgü kodlar döndürür:

error	Nerede	Anlamı
`too_many_phones`	POST /contacts/sync	Tek çağrıdaki numara limiti aşıldı; listeyi parçalayın.
`invalid_date`	POST /messages/schedule	scheduled_at geçerli bir ISO 8601 tarihi değil.
`invalid_trigger_type`	POST /auto-replies	trigger_type izin verilen değerlerden biri değil.
`content_blocked`	POST /messages/send	Mesaj içeriği politika kontrolüne takıldı.
`no_media`	GET /messages/{messageId}/media	Mesajda medya eki yok.
`invalid_filename`	GET /media/{filename}	Dosya adı geçersiz karakter içeriyor.

Güvenlik katmanından dönen yanıtlar

Yanıt gövdesi JSON değil de error code: 1010 gibi tek satırlık düz bir metinse, isteğiniz API'ye hiç ulaşmamıştır — önündeki güvenlik katmanı kesmiştir. Bu durumda anahtarınızı veya gövdenizi düzeltmek sonucu değiştirmez.

HTTP	Gövde	Anlamı	Ne yapmalı
`403`	`error code: 1010`	İstemcinizin User-Agent başlığı engellendi.	Anlamlı bir `User-Agent` gönderin, örneğin `SirketAdi-Entegrasyon/1.0`.

Varsayılan User-Agent tuzağı

Bazı HTTP kütüphaneleri kendi adını User-Agent olarak gönderir (örneğin Python urllib, libwww-perl) ve bu değerler engellenir. curl, requests, axios, okhttp gibi istemcilerde sorun görülmez. Her entegrasyonda kendi uygulama adınızı taşıyan bir User-Agent kullanmak en güvenli yoldur.

Yeniden deneme stratejisi

4xx hatalarını tekrar denemeyin — istek düzelmeden sonuç değişmez. Tek istisna 429: limit penceresi geçtikten sonra denenmelidir.

5xx ve ağ hataları için üstel geri çekilme (örneğin 1s, 2s, 4s, 8s) ve makul bir üst sınır kullanın. Gönderim uçlarında tekrar denerken kendi tarafınızda bir istek kimliği tutun ki aynı mesajı iki kez göndermeyin.

Çift gönderim tuzağı

Zaman aşımı alan bir gönderim isteği sunucuda başarılı olmuş olabilir. Otomatik tekrar denemeden önce GET /chats/{chatId}/messages ile son mesajı doğrulayın veya webhook olayını bekleyin.