Sorun Giderme

Webhook'lar Uç Noktanıza Ulaşmıyor

Belirtiler: API üzerinden bir webhook gönderirsiniz, ancak uç noktanız asla almaz.

Olası nedenler:

• Uç nokta pasif — Dashboard'da uç noktanın etkin olup olmadığını kontrol edin
• Olay filtresi uyumsuzluğu — Webhook'un olay türü, uç noktanızın filtresiyle eşleşmiyor
• SSRF koruması — HookSniff, localhost, özel IP'ler ve dahili alan adlarına teslimatı engeller
• Güvenlik duvarı engellemesi — Sunucunuz HookSniff'in giden IP'lerini engelliyor olabilir

Çözüm: GET /v1/webhooks ile teslimat durumunu kontrol edin ve hata mesajları için teslimat detaylarına bakın.

401 Yetkisiz

Belirtiler: Her API isteği 401 döndürüyor.

Olası nedenler:

• API anahtarı eksik veya hatalı — Bearer hr_live_... formatında olmalı
• API anahtarı silinmiş veya döndürülmüş
• Programmatik erişim için API anahtarı yerine JWT token kullanılıyor

Çözüm: Dashboard'da yeni bir API anahtarı oluşturun ve ortam değişkeninizi güncelleyin.

İmza Doğrulaması Başarısız

Belirtiler: Uç noktanız webhook'ları "Geçersiz imza" ile reddediyor.

Olası nedenler:

• Yanlış gizli anahtar — Uç noktanın mevcut imza gizli anahtarını kullanın, eskisini değil
• Gövde değişikliği — Express.js body parser ham gövdeyi değiştirir. express.raw() kullanın
• Kodlama uyumsuzluğu — JSON.stringify(parsed) yerine ham istek gövdesine karşı doğrulayın
• Gizli anahtar rotasyonu — Eski gizli anahtarlar rotasyondan sonra 24 saat boyunca geçerli kalır

Çözüm: Doğrulama kodu için Güvenlik sayfasına bakın. Security

429 Hız Sınırlı

Belirtiler: API istekleri 429 Çok Fazla İstek döndürüyor.

Neden: Planınızın dakika başına istek limitini aştınız.

Çözüm: Retry-After başlık süresini bekleyin, ardından üstel geri çekilme ile tekrar deneyin. Detaylar için Hız Sınırlama sayfasına bakın.

Teslimatlar Beklemede Takılı Kaldı

Belirtiler: Webhook'lar uzun süre "beklemede" olarak görünüyor.

Olası nedenler:

• Worker çalışmıyor — Teslimat worker'ı çalışmıyor olabilir
• Kuyruk birikmesi — Yüksek hacim gecikmelere neden olabilir
• Uç nokta zaman aşımı — Uç noktanız yanıt vermek için çok uzun sürüyor (30s limit)

Çözüm: Worker durumunu kontrol edin (kendi kendine barındırma için make status) veya dashboard sağlık göstergesini kontrol edin (bulut).

Yüksek Başarısızlık Oranı

Belirtiler: Birçok teslimat başarısız oluyor.

Olası nedenler:

• Uç nokta 5xx döndürüyor — Sunucunuzda bir sorun var
• Uç nokta 4xx döndürüyor — Uç noktanız istekleri reddediyor (kimlik doğrulamayı kontrol edin)
• DNS hatası — Uç nokta URL'nize erişilemiyor
• TLS hatası — Uç noktanızda sertifika sorunu

Çözüm: Spesifik hata mesajları için dashboard'daki teslimat denemelerini kontrol edin.

Webhook Limitine Ulaşıldı

Belirtiler: API, "webhook limiti aşıldı" ile 403 döndürüyor.

Neden: Planınızın aylık webhook limitine ulaştınız.

Çözüm: GET /v1/billing/usage ile kullanımı kontrol edin. Planınızı yükseltin veya bir sonraki fatura dönemini bekleyin.