Hata Yönetimi (Error Handling)

Partner API, standart HTTP durum kodları kullanır ve tutarlı JSON hata yanıtları döndürür.

Hata Yanıt Formatı

Tüm hatalar şu yapıyı takip eder:

{
	"statusCode": 400,
	"message": "Validation failed",
	"error": "Bad Request"
}

Durum Kodları

Kod	Hata	Açıklama
`400`	Bad Request	Geçersiz istek gövdesi, eksik zorunlu alanlar veya doğrulama hatası
`401`	Unauthorized	Eksik, geçersiz veya süresi dolmuş kimlik doğrulama bilgileri
`403`	Forbidden	Geçerli kimlik bilgileri ancak bu işlem için yetersiz yetki
`404`	Not Found	İstenen kaynak mevcut değil
`409`	Conflict	Mükerrer istek algılandı (ör. farklı yük ile mükerrer idempotency anahtarı)
`429`	Too Many Requests	Hız sınırı aşıldı
`500`	Internal Server Error	Sunucuda beklenmeyen bir hata oluştu

Doğrulama Hataları (Validation Errors)

İstek doğrulamasından kaynaklanan 400 hataları için message alanı, hangi alanların doğrulamadan geçemediğine dair ayrıntılar içerebilir:

{
	"statusCode": 400,
	"message": [
		"products.0.productId must be a UUID",
		"products.0.startAt must be a valid ISO 8601 date",
		"payment.type must be one of: CARD, GOOGLE_PAY, APPLE_PAY, IDEAL, REVOLUT, BANCONTACT"
	],
	"error": "Bad Request"
}

En İyi Uygulamalar

Hata kategorisini belirlemek için her zaman statusCode alanını kontrol edin.
401 hataları için API anahtarınızı, zaman damgası güncelliğini (5 dakika içinde), nonce benzersizliğini ve imza hesaplamasını doğrulayın.
Sipariş oluşturmadaki 409 hataları için orijinal sipariş zaten işlenmiştir. Idempotency anahtarı veya harici referans kullanarak siparişi sorgulayın.
500 hataları için üstel geri çekilme ile yeniden deneyin. Hata devam ederse destek ile iletişime geçin.