Hata Kodları

Hatalar ortak hata zarfıyla döner. Dallanmayı message'a göre değil, code'a göre yapın; message dile göre değişir. Zarfın alanları ve genel kurallar: Hata Yönetimi.

{
  "status": "failure",
  "code": "insurance.validation.invalid",
  "message": "Sigorta isteği geçersiz — ayrıntılar `details.errors` alanında.",
  "statusCode": 422,
  "requestId": "00000000-0000-0000-0000-000000000000",
  "details": {
    "errors": [{ "field": "currency", "reason": "currency_mismatch" }]
  }
}

Hata yanıtında docsUrl alanı bulunduğunda, bu sayfadaki ilgili kodun açıklamasına gider.

Kodlar insurance.<alan>.<sebep> biçimindedir ve her biri tek bir anlam taşır. Ayrıntı details alanındadır: alan ihlallerinde details.errors[], durum çakışmalarında details.reason, yeniden denenebilir hatalarda details.retryable: true. Gönderdiğiniz kişisel veriler, sağlayıcının kodları ve ham mesajları hata yanıtına girmez.

Özet

API istekleri

Siparişte ve webhook'ta görülen kodlar

Poliçe, iptal ve iade işleri isteğinizden sonra arka planda yürür. Bu işlerin hatası istek yanıtında değil, siparişin errorCode ya da refundErrorCode alanında ve webhook yükünün errorCode alanında görünür.

Poliçe işi sırasında teklif aşamasının kodları da (insurance.quote.declined, insurance.reference.unknown, insurance.validation.invalid) errorCode olarak görülebilir; anlamları aşağıdaki gibidir.

Panel

Checkout Form

Teklif ve uygunluk

insurance.validation.invalid

İstek sigorta kurallarına uymuyor: eksik ya da biçim dışı alan, saat dilimi olmayan zaman damgası, ondalık tutar, tanınmayan alan. İhlallerin hepsi tek yanıtta details.errors[] içinde döner; her öğe field (alan yolu, ör. tickets[0].departureAt) ve reason (sebep) taşır. Gönderdiğiniz değer yanıta yazılmaz.

Sık görülen sebepler:

Sebep listesi zamanla genişleyebilir; tanımadığınız bir sebebi o alanın geçersiz olduğu şeklinde ele alın. İsteği düzeltip yeniden gönderin. Biçimler: Veri Biçimleri.

insurance.reference.unknown

İstekteki bir referans kodu (ör. ülke, il, ilçe) tanınmıyor ya da bağlantınızın sağlayıcısı için karşılığı yok. Alan yolu details.errors[].field alanındadır (reason: unknown_reference), referans türü details.kind alanındadır. Geçerli kodları GET /api/v1/insurance/reference/{kind} ucundan alın; tahmini ya da boş değer göndermeyin.

insurance.type.not_available

İstenen sigorta tipi şu anda sunulamıyor: tip hesabınıza açık değil, sepet uygunluk koşullarını karşılamıyor, bu tip için bağlantılarınızda açık bir ürün yok ya da yalnızca sepet kalemiyle satılan tip sepet kalemi olmadan istendi (Sepet Kalemi Olmadan Satış). Uygun tipleri Uygunluk ucundan alın.

Talep tiplerinde de aynı kod döner: talep tipi için teklif istendi, talep istenen tip bir talep tipi değil ya da bağlantılarınızda bu tip için talep alan bir ürün yok. Bkz. Talep.

insurance.quote.declined

Sağlayıcı bu bilgilerle teklif vermedi. Aynı bilgilerle tekrar denemek sonucu değiştirmez. Ödemeye sigortasız devam edebilirsiniz.

insurance.quote.not_found

Teklif ya da seçenek bulunamadı: kimlik yanlış ya da başka bir hesaba ait. Kimliği Teklif yanıtından aynen alın.

insurance.quote.expired

Teklifin geçerlilik süresi doldu. Yeni teklif alın ve siparişi yeni seçenekle oluşturun.

insurance.quote.stale

Teklif güncel değil: tekliften sonra sepet, sigortalanan kalemler ya da sigortalı bilgileri değişti. Örneğin ödemenin sigorta alanlı kalemleri teklifteki kalemlerden farklı. Yeni teklif alın.

insurance.facility.not_supported

Bu seçenek için anlaşmalı kurum listesi sunulmuyor: seçeneğin bağlantınızdaki ürünü kurum listesi vermiyor. İstek sağlayıcıya gönderilmez. Tekrar denemek sonucu değiştirmez; seçenek bundan etkilenmez. Bkz. Teklif › Anlaşmalı kurumlar.

Sepet kalemi ön verisi

Sepet kaleminin sigorta ön verisi (insuranceData) için ayrı bir hata kodu yoktur. Ön veri şu yanıtlarda görünür:

Sipariş ve ödeme

insurance.order.not_found

Sipariş bulunamadı: kimlik yanlış ya da başka bir hesaba ait. Sipariş kimliği inso_ önekiyle başlar.

insurance.order.state_conflict

Siparişin durumu bu işleme izin vermiyor; örneğin sipariş başka bir ödemeye bağlı, poliçe henüz kesilmedi ya da iade zaten tamamlandı. Sebep details.reason alanındadır. Aynı istekle tekrar denemek sonucu değiştirmez.

Sebeplerin anlamı: Sipariş ve Ödeme Bağlama › Durum çakışması, iptal ve iade için İptal ve Prim İadesi.

insurance.order.premium_item_mismatch

Ödemenin sepetindeki prim kalemi siparişle eşleşmiyor. Prim kalemi tam bir kez bulunmalıdır: id sipariş kimliği, itemType VIRTUAL, tek birim ve tutarı prim. Sebep details.reason alanındadır: Sipariş ve Ödeme Bağlama › Ödemeye bağlama.

insurance.order.payment_not_recorded

Ödemenin sepeti sigorta için kayıtlı değil: ödeme sigorta alanlı kalemlerle oluşturulmadı ya da ödeme oluşturulurken sigorta hesabınızda açık değildi. Ödemeyi sigorta alanlı kalemlerle oluşturun: Prim ve Ödeme.

insurance.idempotency.conflict

Aynı Idempotency-Key daha önce farklı bir istekle kullanıldı. Yeni bir işlem için yeni anahtar üretin; aynı işlemi tekrarlıyorsanız ilk istekteki gövdeyi aynen gönderin. Bkz. Akışlar › Idempotency-Key.

insurance.premium.not_captured

Prim tahsil edilmedi.

• İstek yanıtında: Prim tahsil edilmeden poliçe ya da prim iadesi istendi. Önce primin tahsil edilmesini bekleyin.
• Siparişte ve webhook'ta (errorCode): Ödeme tahsil edilmeden iptal edildi, süresi doldu ya da kesin olarak başarısız oldu. Tahsilat FAILED olur ve poliçe istenmez. Prim alınmadığı için iade gerekmez.

Sağlayıcı tahsilatı

Primi sağlayıcının tahsil ettiği siparişlerde görülen kodlar. Akış: Sağlayıcı Tahsilatı.

insurance.payment.merchant_payment_not_captured

Siparişe bağlı Lunixi ödemeniz henüz tahsil edilmediği için prim çekilemez. Sizin ödemeniz alınmadan sağlayıcıya ödeme gönderilmez. Ödeme tahsil edildikten sonra isteği tekrarlayın.

insurance.payment.method_not_supported

Bu sipariş için sağlayıcı tahsilatı istenen biçimde kullanılamıyor. Sebep details.reason alanındadır: Sağlayıcı Tahsilatı › Desteklenmeyen tahsilat. Aynı istekle tekrar denemek sonucu değiştirmez.

insurance.card.invalid

Kart bilgisi geçersiz: kart numarası doğrulamadan geçmiyor, kartın süresi dolmuş ya da bir alan biçim dışı. Geçersiz alan details.field alanındadır; kartın değerleri hata yanıtına girmez. Sağlayıcıya istek gitmez. Alanı düzeltip yeniden gönderin.

insurance.card.pci_required

Ürün primi kartla çekiyor, ancak hesabınız PCI-DSS sertifikalı olarak tanımlı değil. API'ye ham kart bilgisini yalnızca PCI-DSS sertifikalı merchant'lar gönderebilir. Kart işlenmez ve saklanmaz, sağlayıcıya istek gitmez. Aynı istekle tekrar denemek sonucu değiştirmez: Sağlayıcı Tahsilatı › Kart bilgisi.

insurance.payment.declined

Sağlayıcı prim çekimini reddetti. Bu kod çekim denemesinin failureCode, siparişin errorCode ve insurance.policy.failed yükünün errorCode alanında görülür. Tahsilat FAILED olur ve poliçe istenmez; sizin ödemeniz geçerli kalır. Alıcı başka bir kartla denemek isterse yeni bir Idempotency-Key ile yeni deneme başlatabilirsiniz.

insurance.payment.not_found

Alıcının yönlendirildiği sağlayıcı ödeme adresi artık geçerli değil: dönüş işlendi ya da deneme alıcının adımını beklemiyor. Siparişin durumunu sipariş ucundan izleyin.

Poliçe, iptal ve iade

insurance.policy.not_found

Poliçe bulunamadı: kimlik yanlış ya da başka bir hesaba ait. Poliçe kimliğini siparişin policies[] dizisinden alın.

insurance.policy.issue_failed

Sağlayıcı poliçeyi kesin olarak kesmedi; otomatik olarak yeniden denenmez. Siparişte poliçe FAILED_FINAL olur. Prim tahsil edildiyse iade REQUIRED olur ve primin iade edilmesi gerekir: İptal ve Prim İadesi › İade gerekiyor.

insurance.policy.issue_deadline_passed

Poliçe, ürünün son tarihine (ör. teminat başlangıcı) kadar kesilemedi; bu tarihten sonra yeni poliçe kesilmez. Siparişte poliçe FAILED_FINAL olur. Prim tahsil edildiyse iade REQUIRED olur.

Sağlayıcı poliçeyi bu tarihten önce kestiyse ve sonuç sonradan kesinleşirse, iade başlamadıysa poliçe ISSUED olur ve insurance.policy.issued gelir. Bkz. Webhook Olayları.

insurance.policy.cancel_failed

Sağlayıcı iptal talebini kesin olarak reddetti (ör. teminat başladı ya da iptal süresi geçti). Poliçe yürürlükte kalır: siparişin poliçe durumu ISSUED ya da PARTIALLY_ISSUED olur. İptal otomatik olarak yeniden denenmez. Bkz. İptal ve Prim İadesi › Poliçe iptali.

insurance.refund.rejected

Prim iadesi ödeme tarafında yapılamadı; para hareket etmedi. Siparişte iade FAILED olur ve kod refundErrorCode alanına yazılır. İadeyi prim iadesi ucuyla yeniden başlatabilir ya da kendi kanalınızdan yapabilirsiniz.

Hasar kaydı

Hasar kaydı uçlarında görülen kodlar. Akış: Hasar Kaydı.

Hasar kaydı kesin olarak başarısız olduğunda sebep, kaydın errorCode alanında ve insurance.claim.failed yükünün claim.errorCode alanında da görülür: insurance.claim.rejected ya da insurance.provider.unavailable.

insurance.claim.not_found

Hasar kaydı bulunamadı: kimlik yanlış ya da başka bir hesaba ait. Hasar kaydı kimliği insclm_ önekiyle başlar.

insurance.claim.state_conflict

Poliçenin ya da hasar kaydının durumu bu işleme izin vermiyor; örneğin poliçe yürürlükte değil, poliçede açık bir hasar kaydı var ya da belge istenen kayıt sağlayıcıya ulaşmadı. Sebep details.reason alanındadır. Aynı istekle tekrar denemek sonucu değiştirmez.

Sebeplerin anlamı: Hasar Kaydı › Durum çakışması.

insurance.claim.not_supported

Bu poliçe için hasar kaydı açılamaz: poliçenin sigorta tipi ya da bağlantınızdaki ürün hasar kaydını desteklemiyor. Tekrar denemek sonucu değiştirmez. Bkz. Hasar Kaydı › Hasar kaydı açılabilen poliçeler.

insurance.claim.rejected

Sağlayıcı hasar kaydını kabul etmedi. Kayıt FAILED olur ve insurance.claim.failed gönderilir. Aynı istekle tekrar denemek sonucu değiştirmez. Gerekirse yeni bir Idempotency-Key ile yeni hasar kaydı açabilirsiniz.

Talep

Talep uçlarında görülen kodlar. Akış: Talep.

Talep kesin olarak başarısız olduğunda sebep, talebin errorCode alanında da görülür: insurance.lead.rejected, insurance.validation.invalid ya da insurance.provider.unavailable.

insurance.lead.not_found

Talep bulunamadı: kimlik yanlış ya da başka bir hesaba ait. Talep kimliği insl_ önekiyle başlar.

insurance.lead.rejected

Sağlayıcı talebi kabul etmedi. Talep FAILED olur; details.leadId talebin kimliğini taşır. Aynı istekle tekrar denemek sonucu değiştirmez. Bilgileri düzeltip yeni bir Idempotency-Key ile yeni talep açabilirsiniz.

Belge

insurance.document.not_supported

İstenen belge türü bu poliçe için sunulmuyor: poliçenin bağlantınızdaki ürünü makbuz ya da sertifika vermiyor. İstek sağlayıcıya gönderilmez. Tekrar denemek sonucu değiştirmez; poliçe belgesi bundan etkilenmez. Bkz. Poliçe Belgesi › Makbuz, Sertifika.

insurance.document.unavailable

Poliçe belgesi ya da sağlayıcının hasar belgesi şu anda sağlayıcıdan alınamıyor (details.retryable: true). Poliçe ve hasar kaydı geçerli kalır; durumları değişmez. İsteği bir süre sonra, tekrarlar arasındaki beklemeyi artırarak yineleyin. Bkz. Poliçe Belgesi, Hasar Kaydı › Sağlayıcının hasar belgesi.

Bağlantı ve sağlayıcı

insurance.provider.unavailable

Bağlantınızın sağlayıcısına şu anda ulaşılamıyor (details.retryable: true). İstek başka bir sağlayıcıya aktarılmaz. Bir süre sonra, tekrarlar arasındaki beklemeyi artırarak yeniden deneyin.

insurance.provider.not_integrated

Bağlantınızın sağlayıcısında bu işlem şu anda kullanılamıyor (ör. bağlantı testi, iptal ya da belge). Tekrar denemek sonucu değiştirmez.

insurance.provider.not_configured

Bağlantınızın sağlayıcısı bu ortamda şu anda kullanıma hazır değil. İsteğinizde düzeltilecek bir şey yoktur. Sorun sürerse yanıttaki requestId değeriyle destek ekibine başvurun.

insurance.connection.not_found

Sigorta bağlantısı bulunamadı: kimlik yanlış, bağlantı kaldırılmış ya da başka bir hesaba ait.

insurance.connection.credentials_rejected

Bağlantıyı test et sonucunda döner: sağlayıcı, bağlantıya girdiğiniz kimlik bilgisini kabul etmedi. Sağlayıcınızın bağlantının ortamı için verdiği kimlik bilgisini kontrol edin. Bkz. Test Ortamı › Test bağlantısı.

insurance.traffic.not_found

Panelde açılmak istenen sigorta istek kaydı bulunamadı: kimlik yanlış ya da kayıt başka bir hesaba ait.

Checkout Form

Bu kodlar Checkout Form'un sigorta isteklerinde ve sigortalı ödeme gönderiminde döner. Form bunları kendisi ele alır ve alıcıya seçenek sunar; sizin ek bir şey yapmanız gerekmez. Ödeme kayıtlarınızı ve alıcı şikâyetlerini incelerken bu açıklamalara başvurabilirsiniz. Alıcının gördüğü: Davranış Kuralları.

payment.insurance.* kodları yalnızca alıcı sigorta seçtiyse döner. Hepsi ödeme denemesinden önce döner: ödeme denemesi başlamaz ve para hareketi olmaz. details.canContinueWithoutInsurance: true alıcının ödemeye sigortasız devam edebileceğini gösterir.

payment.insurance.unavailable

Sigorta seçimi o an doğrulanamadı (details.retryable: true). Alıcı yeniden deneyebilir ya da sigortasız devam edebilir.

payment.insurance.selection_rejected

Sigorta seçimi bu ödemede kullanılamıyor; örneğin teklifin süresi doldu ya da seçim kaldırıldı. Sebebin sigorta kodu details.insuranceCode alanındadır (ör. insurance.quote.expired, insurance.quote.stale, insurance.selection.inactive). Alıcı yeni teklif alabilir ya da sigortasız devam edebilir.

payment.insurance.not_applicable

Sigorta bu ödemeye eklenemiyor. Sebep details.reason alanındadır:

Alıcı ödemeye sigortasız devam edebilir.

payment.insurance.installment_not_supported

Sigortalı ödeme yalnızca tek çekimle yapılabilir. Alıcı tek çekimle ödeyebilir ya da sigortasız devam edebilir.

insurance.selection.not_found

Sigorta seçimi bulunamadı ya da bu ödemeye ait değil.

insurance.selection.locked

Ödeme gönderildiği için sigorta seçimi artık değiştirilemez ya da kaldırılamaz.

insurance.selection.inactive

Sigorta seçimi artık geçerli değil: alıcı seçimi kaldırdı, yeni bir seçim yaptı ya da seçimin süresi doldu. Alıcı yeni teklif alabilir ya da sigortasız devam edebilir.

insurance.checkout.session_required

Checkout Form oturumu olmadan sigorta isteği yapıldı. Bu uçlar yalnızca Lunixi ödeme formu tarafından çağrılır.

insurance.checkout.session_invalid

Checkout Form oturumu geçersiz ya da süresi dolmuş. Alıcının ödeme formunu yeniden açması gerekir.

Genel

insurance.dependency.unavailable

İşlem şu anda tamamlanamıyor (details.retryable: true). İsteğinizde düzeltilecek bir şey yoktur. Aynı istekle ve aynı Idempotency-Key ile bir süre sonra yeniden deneyin.

insurance.internal.integrity

İstek sunucu tarafında tamamlanamadı; isteğinizde düzeltilecek bir şey yoktur. Üstel geri çekilmeyle yeniden deneyin. Sorun sürerse yanıttaki requestId değeriyle destek ekibine başvurun.

insurance.auth.scope_missing

İstek bu sigorta işlemi için gereken yetkiyi taşımıyor. İsteğinizde düzeltilecek bir alan yoktur. Sorun sürerse yanıttaki requestId değeriyle destek ekibine başvurun.

insurance.auth.caller_not_allowed

Bu sigorta işlemi bu çağıran için yapılamaz. İsteğinizde düzeltilecek bir alan yoktur. Sorun sürerse yanıttaki requestId değeriyle destek ekibine başvurun.

Ortak kodlar

Sigorta uçlarında aşağıdaki platform kodları da dönebilir. Anlamları ve çözümleri ortak sayfalardadır:

İlgili

• Webhook Olayları: errorCode taşıyan olaylar
• Akışlar › Yanıt ve hatalar: API yolunun hata kuralları
• Kavramlar ve Durumlar: durum eksenleri