Hatalar

Bütün hatalar aynı biçimde döner: Content-Type: application/problem+json ve RFC 9457 Problem Details gövdesi.

Hata biçimi

409 Conflict

{
  "type": "urn:trimango:reservation:price-changed",
  "title": "Fiyat değişti",
  "status": 409,
  "total": 4850,
  "currency": "EUR",
  "total_try": 177025
}

Alan	Anlamı
type	Hatanın türü, urn:trimango:<kod> biçiminde. Kararınızı bu alana göre verin.
title	İnsanın okuyacağı kısa açıklama (Türkçe). Metni değişebilir; koda bağlamayın ve olduğu gibi misafire göstermeyin.
status	HTTP durum kodu, yanıtın koduyla aynı.
errors	Yalnız alan hatalarında: alan yolu → mesaj.
Ek alanlar	Bazı türler ek bilgi taşır: retry_after, total, currency, total_try (aşağıda).

Bu sayfada türler kısaca urn:trimango: öneki olmadan yazılır: reservation:price-changed.

Tanımadığınız bir type gelirse HTTP durum koduna göre davranın (4xx isteğinizde, 5xx bizde bir sorun). Yeni türler habersiz eklenebilir.

Alan hataları

Gövdedeki bir alan kurala uymazsa yanıt 422 olur ve errors nesnesi hangi alanın neden kabul edilmediğini söyler. Anahtarlar istekteki alan yoludur, snake_case:

422 Unprocessable Content

{
  "type": "urn:trimango:validation",
  "title": "Alanları kontrol et",
  "status": 422,
  "errors": {
    "check_out": "Konaklama en az 7 gece olmalı",
    "guest.phone": "Telefonu ülke koduyla yazın"
  }
}

İç içe alanlar noktayla (guest.phone), dizi elemanları sırasıyla (items.0.check_in) yazılır. 422’de type her zaman validation olmayabilir; alan hatalarını errors nesnesinden okuyun. Mesajlar Türkçedir ve acenteye gösterilebilir.

Sorgu ya da yol parametresi okunamazsa (ör. sayı beklenen yerde metin) yanıt 400, türü bad-request olur; errors yine parametre → mesaj taşır.

Sık görülen hatalar

Her uçta

HTTP	type	Anlamı	Ne yapmalı
401		Kimlik yok, yanlış ya da istemci iptal edilmiş. WWW-Authenticate: Basic başlığı gelir.	Yeniden denemeyin; kimliği kontrol edin. Kimlik
429		İstemci başına dakikalık sınır aşıldı.	Retry-After başlığındaki saniye kadar bekleyin. Sınırlar
403	site-api:channel-partner-suspended	Kanal ortaklığınız askıya alınmış; bütün istemcileriniz reddedilir.	Yeniden denemeyin; Trimango ekibiyle iletişime geçin.
403	site-api:not-for-channel-partners	Çağırdığınız uç bu belgede yer almıyor; kanal ortaklarına açık değil.	Yalnız API başvurusundaki uçları kullanın.
400	bad-request	Sorgu ya da yol parametresi okunamadı.	İsteği düzeltin.
422		Gövdedeki ya da sorgudaki bir değer kurala uymuyor.	errors nesnesine bakın.

Katalog ve fiyat

HTTP	type	Uç	Anlamı ve ne yapmalı
404		GET /villas/{slug}, POST /quotes	Villa yok ya da artık satışta görünmüyor (taslak, yayından kaldırılmış, arşivlenmiş). Villayı kendi kataloğunuzdan kaldırın.
422		POST /quotes, /quotes/batch, /quotes/recheck	Tarih ya da kişi sayısı kurala uymuyor: konaklama 1–120 gece, giriş bugünden önce olamaz, adults en az 1; toplu teklifte 1–48 villa, yeniden hesaplamada 1–12 satır.

Villa dolu ya da konaklama kuralına uymuyorsa teklif uçları hata dönmez: yanıt 200’dür, bookable (ya da ok) false ve reason doludur. Ayrıntı: Fiyat ve teklif.

Rezervasyon talebi (POST /reservations)

HTTP	type ya da alan	Anlamı	Ne yapmalı
409	reservation:price-changed	Gönderdiğiniz expected_total güncel toplamla tutmuyor; talep açılmadı. Gövdede güncel total, currency ve total_try.	Yeni toplamı acenteye gösterin, onay alın, yeni expected_total ile aynı submission_id’yi kullanarak yeniden gönderin.
409	reservation:not-available	Gecelerden en az biri dolu.	Teklifi yenileyin, başka tarih ya da villa önerin.
409	villa:not-for-sale	Villa şu an satışa kapalı.	Villanın detayını yeniden okuyun; closed_until doluysa o güne kadar satmayın.
422	check_in, check_out	En az gece, en çok gece, giriş günü kuralı ya da fiyatı girilmemiş gece.	Mesajı acenteye gösterin; tarihleri değiştirin.
422	adults	Kişi sayısı villanın kapasitesini aşıyor.	Kişi sayısını düzeltin.
422	coupon	Kupon geçersiz; talep açılmadı.	Kuponu kaldırıp yeniden gönderin.
422	guest.name, guest.phone, guest.email	Misafir bilgisi eksik ya da biçimi yanlış.	Alanı düzeltin.
404		Villa bulunamadı.	Villayı kataloğunuzdan kaldırın.
429	site:visitor-rate-limit	Gönderim sıklığı sınırı aşıldı. Gövdede retry_after (saniye).	retry_after kadar bekleyin.

Rezervasyon okuma ve sorgu

HTTP	type	Uç	Anlamı ve ne yapmalı
403	reservation:token-expired	GET /reservations/{code}, POST /reservations/{code}/payments	Erişim anahtarının süresi dolmuş. POST /reservations/lookup ile yeni anahtar alın.
404		aynı uçlar	Rezervasyon numarası ya da erişim anahtarı tutmuyor.
404		POST /reservations/lookup	Numara ile e-posta ya da telefon eşleşmedi (hangisinin tutmadığı söylenmez).
429	reservation:too-many-attempts	POST /reservations/lookup	Aynı numaraya bir saatte 10 tutmayan deneme yapıldı. Gövdedeki retry_after (saat dolana kalan saniye) kadar bekleyin.
429	site:visitor-rate-limit	POST /reservations/lookup	Sorgu sıklığı sınırı aşıldı; retry_after kadar bekleyin.

Ödeme başlatma (POST /reservations/{code}/payments)

HTTP	type ya da alan	Anlamı
409	reservation:payment-not-open	Rezervasyon ödeme bekleyen durumda değil (ödeme henüz açılmadı ya da kapandı). Detayı yeniden okuyun.
409	payment:fx-missing	Rezervasyonun kuru henüz yok; biraz sonra yeniden deneyin.
409	payment:card-unavailable	Kartla ödeme şu an açık değil.
422	portion, success_url, failure_url, pending_url	Seçilen ödeme bölümü ya da dönüş adresi kabul edilmedi.

Ödeme akışını Trimango ekibi yürütür; ayrıntı Rezervasyon rehberinde.

Yeniden deneme

Ne zaman yeniden denenir:

Durum	Öneri
Bağlantı hatası, zaman aşımı, 502, 503, 504	Artan aralıklarla yeniden deneyin: ör. 1 sn, 2 sn, 4 sn, 8 sn; her bekleyişe küçük bir rastgele pay ekleyin. 4–5 denemeden sonra vazgeçip kaydedin.
500	Bir kez yeniden deneyin; sürerse vazgeçip size verilen iletişim kanalından bildirin.
429	Retry-After başlığı ya da gövdedeki retry_after kadar bekleyin, sonra deneyin. Daha erken denemeyin.
400, 401, 403, 404, 409, 422	Aynı isteği değiştirmeden yeniden denemeyin; sonuç değişmez. İsteği düzeltin ya da akışı değiştirin.

Hangi istek güvenle tekrarlanır:

İstek	Tekrar güvenli mi
Bütün GET istekleri	Evet.
POST /quotes, /quotes/batch, /quotes/recheck	Evet; yalnız hesaplar, kayıt açmaz.
POST /reservations	Aynı submission_id ile evet. Aynı kimlikle gelen ikinci istek yeni rezervasyon açmaz; ilk talebi 200 ile döndürür. Yeni bir submission_id ile tekrar yeni bir talep açar.
POST /reservations/lookup	Evet, ama her tutmayan deneme numara başına sayaca girer.
POST /reservations/{code}/payments	Evet; aynı bölüm ve tutar için bekleyen ödeme linki yeniden döner.

Zaman aşımında rezervasyon talebi

POST /reservations zaman aşımına uğradıysa talep açılmış olabilir. Aynı submission_id ile yeniden gönderin: talep açıldıysa aynı rezervasyon döner, açılmadıysa şimdi açılır. Yeni submission_id üretmeyin; çift rezervasyona yol açar.