Hata Kodları
HookSniff API tarafından döndürülen tüm hata kodlarının referansı.
Hata Yanıt Formatı
Tüm hatalar tutarlı bir JSON yapısı izler:
{
"error": {
"code": "BAD_REQUEST",
"message": "Invalid request body or parameters"
}
}code alanı makine tarafından okunabilir bir tanımlayıcıdır. message alanı insan tarafından okunabilir bir açıklamadır.
HTTP Durum Kodları
| Durum | Kod | Anlamı | Yaygın Neden |
|---|---|---|---|
| 400 | BAD_REQUEST | Hatalı İstek | Geçersiz JSON, eksik zorunlu alanlar veya doğrulama hatası |
| 401 | UNAUTHORIZED | Yetkisiz | Eksik veya geçersiz API anahtarı, süresi dolmuş JWT token |
| 403 | FORBIDDEN | Yasak | Yetersiz izinler, plan limiti aşıldı veya yalnızca yönetici uç noktası |
| 404 | NOT_FOUND | Bulunamadı | Kaynak mevcut değil veya hesabınıza ait değil |
| 409 | CONFLICT | Çakışma | Tekrarlanan kaynak, idempotans anahtarı çakışması |
| 413 | PAYLOAD_TOO_LARGE | Payload Çok Büyük | İstek gövdesi 1 MB limitini aşıyor |
| 429 | RATE_LIMIT_EXCEEDED | Hız Sınırlı | Çok fazla istek — Retry-After başlığını kontrol edin |
| 500 | INTERNAL_ERROR | Dahili Sunucu Hatası | Beklenmeyen hata — devam ederse destek ile iletişime geçin |
Yaygın Hatalar ve Çözümler
401 UNAUTHORIZED
API anahtarınız eksik, geçersiz veya süresi dolmuş.
Çözüm: Authorization başlığınızın Bearer hr_live_... olduğundan ve anahtarın dashboard ayarlarınızda etkin olduğundan emin olun.
400 BAD_REQUEST — Geçersiz endpoint_id
Uç nokta ID'si mevcut değil veya hesabınıza ait değil.
Çözüm: GET /v1/endpoints ile uç noktalarınızı listeleyin ve geçerli bir ID kullanın.
429 RATE_LIMIT_EXCEEDED
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. Bu sık oluyorsa planınızı yükseltmeyi düşünün.
403 FORBIDDEN — Webhook limiti aşıldı
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.
413 PAYLOAD_TOO_LARGE
Webhook payload'ı 1 MB limitini aşıyor.
Çözüm: Payload boyutunu azaltın. Yalnızca gerekli verileri gönderin. Büyük payload'lar göndermeniz gerekiyorsa, depolamaya yükleyip webhook'ta bir URL eklemeyi düşünün.
İdempotans Hataları
Idempotency-Key başlığını kullanırken:
- Aynı anahtar 24 saat içinde kullanılırsa, önbelleğe alınmış yanıt döndürülür (hata değil)
- Aynı anahtar farklı parametrelerle kullanılırsa, 409 CONFLICT döndürülür
- Anahtarlar 24 saat sonra sona erer ve güvenle yeniden kullanılabilir