Hatalar ve Dayanıklılık (Errors & Resilience)

Profesyonel bir entegrasyon hataları tek bir başarısız durum olarak ele almaz. Kullanıcı kimliği, işlem yetkisi, kaynak kapsamı, doğrulama ve geçici servis durumları farklı HTTP durum kodları üretir.

Hata Türleri Nasıl Yorumlanır?

• 401 Unauthorized: Kimlik doğrulama hatası. Erişim jetonunun (Access Token) eksik veya süresi dolmuş olduğunu gösterir. Backend, Client Credentials ile yeni token almalıdır.
• 403 Forbidden: Yetki reddi. Gerekli yetki kapsamının (Scope) veya hesap erişiminin bulunmadığını gösterir.
• 404 Not Found: Kaynağın bulunamadığını veya müşteri yetki sınırının (Tenant Isolation) dışında kaldığını bildirir.
• 400 Bad Request: Doğrulama hatası. Eksik, bilinmeyen veya iş kurallarına uymayan alanları belirtir.
• 409 Conflict: Aynı Idempotency-Key farklı bir istek gövdesiyle yeniden kullanılmıştır veya kaynak mevcut durumuyla işlemi kabul edemiyordur.
• 429 Too Many Requests: Hız sınırı (Rate Limit) aşımı. Retry-After yanıt başlığındaki saniye kadar beklenmelidir.
• 500/502/503/504: Sunucu veya ağ geçidi geçici olarak isteği tamamlayamamıştır. Yalnızca güvenli/idempotent işlemler artan bekleme süresi ve rastgele sapma (Exponential Backoff + Jitter) ile tekrar denenmelidir.

İdempotency Neden Gerekli?

Bir POST isteğinin yanıtı ağda kaybolabilir; kayıt sunucuda oluşmuş olsa bile istemci bunu bilemeyebilir. Kayıt oluşturan endpointlerde 8–128 karakterlik benzersiz bir Idempotency-Key gönderildiğinde aynı anahtar ve aynı gövdeyle yapılan tekrar çağrısı ikinci kayıt oluşturmaz. Tekrar oynatılan yanıtta Idempotency-Replayed: true başlığı bulunur.

Hız Sınırı Başlıkları (Rate Limit Headers)

Her yanıt o an geçerli hız sınırını üç başlıkla bildirir:

• X-RateLimit-Limit: Pencere başına izin verilen istek sayısı.
• X-RateLimit-Remaining: Kalan istek hakkı.
• X-RateLimit-Reset: Hakkın tazelenmesine kaç saniye kaldığı.

Sayfalama (Pagination)

Liste uçları bir data dizisiyle birlikte meta ve links nesnelerini döndürür. Sonraki sayfayı kendiniz sayfa numarası artırarak değil links.next üzerinden okuyun; durma koşulu olarak meta.total_pages değerini kullanın. En büyük sayfa boyutu 100’dür.