Hatalar ve tekrar deneme

HTTP durum kodunu ve varsa gövdedeki errorCode alanını birlikte değerlendirin. Mevcut API'de işlem bazında farklı hata gövdeleri bulunabilir; her yanıtın mutlaka aynı JSON alanlarını içerdiğini varsaymayın.

Durum	Yapılacak işlem
400	İstek alanlarını ve dönen doğrulama mesajını kontrol edin. Aynı hatalı isteği tekrar göndermeyin.
401	Erişim token'ını ve hesap bağlamını kontrol edin. Uygunsa bir kez token yenileyin.
403	Kullanıcının işlem yetkisi yetersiz olabilir; tekrar giriş tek başına çözmez.
404	Kaynak bulunamadı veya bu hesap için görünür değil; rezervasyon kimliğini kontrol edin.
409	İşlem çakışmış olabilir; güncel kaydı okuyun, hata koduna göre ilerleyin.
410	Teklif kullanılamıyor; yeniden müsaitlik sorgulayın.
429	İstek hızını azaltın; varsa Retry-After başlığına uyun.
5xx / bağlantı hatası	İşlemin sonuçlanıp sonuçlanmadığını değerlendirin; oluşturma isteğini yeni anahtarla körlemesine tekrarlamayın.

Tablo entegrasyon rehberidir; her endpoint bütün bu durumları döndürmez. İşleme özel belgelenmiş yanıtları API referansında inceleyin.

Hata yanıtını ayrıştırma

message gösterim/teşhis metnidir; iş mantığını Türkçe metin eşleştirmesine bağlamayın. Varsa errorCode ile karar verin. errors bir alan doğrulama özeti taşıyabilir; alan bazlı ayrıntı varsa onu da kullanıcıya gösterin. Boş gövde veya JSON olmayan ağ geçidi yanıtında yalnız HTTP durumu ve güvenli teşhis bilgisiyle çalışabilmelisiniz.

410 için sentetik hata zarfı örneği:

{
  "success": false,
  "message": "Geçersiz veya süresi dolmuş rezervasyon referansı.",
  "data": null,
  "errors": [],
  "statusCode": 410,
  "errorCode": "RESOURCE_GONE",
  "correlationId": "demo-request-correlation"
}

Bu örnek alanların her hata türünde dolu olacağını garanti etmez.

Teklif kaybolduğunda

Rezervasyon akışındaki RESOURCE_GONE / 410; bulunamayan, süresi dolan veya başka aktöre ait bir teklif için dönebilir. Yanıttan bu üç durumu ayırmaya çalışmayın. Doğru oturumla yeni arama yapın, yeni fiyatı kullanıcıya gösterin ve yeni teklifle ilerleyin.

Rezervasyon isteği zaman aşımına uğradığında

Zaman aşımı, rezervasyonun oluşmadığını kanıtlamaz. İlk istekle birlikte Idempotency-Key gönderin. Aynı isteği tekrarlarken aynı anahtarı ve gövdeyi kullanın. Yeni bir rezervasyon için benzersiz bir anahtar üretin.

Bu belge, farklı gövdeyle aynı anahtarın gönderilmesi için belirli bir 409 davranışı veya sabit idempotency saklama süresi taahhüt etmez.

Önerilen istemci politikası:

1. Bir rezervasyon niyeti için anahtarı ağ çağrısından önce kalıcı saklayın.
2. Token yenileme gerekiyorsa aynı hesapta yenileyin; aynı gövde ve anahtarla ilerleyin.
3. Geçici bağlantı/5xx hatasında sınırlı sayıda, beklemeyi artırarak ve rastgele küçük gecikme ekleyerek tekrar deneyin. Sınırsız döngü kurmayın.
4. Sonucu hâlâ bilmiyorsanız liste/detay üzerinden mutabakat yapın ve destekle görüşün. Eski niyet için yeni anahtar üretip ikinci kayıt açmayın.

Başarılı rezervasyon yanıtı alındıktan sonra teklifin süresinin dolması rezervasyonu ortadan kaldırmaz; artık teklif yerine rezervasyon kimliğiyle sorgulayın. Idempotency-Key desteğini güncelleme veya iptal gibi başka endpoint'lere kendiliğinden genellemeyin.

İş akışına özgü hata kodları

Kod	Toparlanma
EXTERNAL_CONDITIONS_ACCEPTANCE_REQUIRED	Güncel teklifin koşullarını gösterin; doğru bacak sürümünü ve kabul alanını gönderin.
EXTERNAL_ROUTE_SUPPORT_REQUIRED	Bu rota için otomatik booking yerine destekle görüşün.
EXTERNAL_SPECIAL_REQUEST_SUPPORT_REQUIRED	Özel ihtiyacın zaman/tedarikçi kısıtını destekle çözün; yalnız nota ekleyerek atlamayın.
EXTERNAL_EXTRAS_INVALID	Katalog kodu, adet ve toplam yolcu sayısını kontrol edip yeniden fiyatlatın.
EXTERNAL_CONTACT_INVALID	Uluslararası lider telefonu ve gerekiyorsa uçuş numarasını düzeltin.
BOOKING_LOCKED_IN_MERGED_GROUP	Kayıt birleşik gruptadır; güncelleme için destekle ilerleyin.

HTTP durumunu yalnız tablodaki kod adına bakarak varsaymayın; gerçek yanıtı okuyun. Bilinmeyen yeni hata kodlarını da güvenli biçimde gösterip kaydedin.

Destek için gerekli bilgiler

İşlem adı, HTTP kodu, istek zamanı ve varsa correlationId / errorCode değerlerini paylaşın. Token, şifre veya yolcu kişisel bilgilerini destek kaydına eklemeyin. İletişim: support@yolcugo.com.