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`	Hız limiti aşıldı.	`X-RateLimit-Reset` anına kadar bekleyin, geri çekilerek yeniden deneyin.
`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.

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.