Hata Yönetimi

Hata yanıtları tek bir zarf kullanır. Hatanın nereden çıktığı (kimlik doğrulama, yetki, iş kuralı, servis) fark etmez — alanlar aynıdır.

{
  "status": "failure",
  "code": "payment.card.declined",
  "message": "Kart reddedildi",
  "statusCode": 409,
  "timestamp": "2026-08-17T10:32:23.816Z",
  "service": "api-gateway",
  "systemTime": 1786962743816,
  "requestId": "req_7f3d9c1a4b2e",
  "docsUrl": "https://docs.lunixi.com/tr/getting-started/errors#INVALID_SIGNATURE"
}

Alanlar

Doğrulama hataları

Alan doğrulaması başarısız olduğunda details alan bazlı döker:

{
  "status": "failure",
  "code": "validation.error",
  "message": "Doğrulama hatası",
  "statusCode": 400,
  "requestId": "req_7f3d9c1a4b2e",
  "details": {
    "errors": [
      { "field": "amount", "errors": ["amount minör birim tam sayı olmalıdır"] }
    ]
  }
}

requestId ile korelasyon

Her yanıt — başarılı ya da hatalı — x-request-id başlığı taşır. Aynı değer gövdedeki requestId alanında ve bizim mikroservis loglarımızda bulunur.

Kendi id'nizi gönderebilirsiniz

İstekte x-request-id (ya da x-correlation-id) gönderirseniz ona saygı duyulur ve aynı değer yanıtta döner. Böylece kendi izleme sisteminizle bizimkini aynı anahtar üzerinden eşleyebilirsiniz.

Çözüm sırası: x-request-id → x-correlation-id → gateway kendi üretir.

Dil seçimi

message alanı ve docsUrl bağlantısı istediğiniz dilde döner.

x-lang: tr

x-lang yoksa Accept-Language kullanılır; o da yoksa kurulumun varsayılan dili geçerlidir.

Desteklenmeyen bir dil istenirse varsayılana düşülür. Sözlükte olmayan bir kod için orijinal mesaj gösterilir — çıplak kod asla gösterilmez.

HTTP durum kodları

Hangi hatada yeniden denenir

Yeniden deneyin: 500 · 502 · 503 · 504 — üstel geri çekilmeyle.

Denemeyin: 400 · 401 · 403 · 409 · 422 — istek aynı kaldığı sürece sonuç değişmez. Önce isteği düzeltin.

Kod sözlüğü

Aşağıdaki kodların her birinin kendi başlığı ya da tablo satırı vardır. Yanıt bir docsUrl taşıyorsa bağlantı doğrudan oraya götürür.

VALIDATION_ERROR

Gönderdiğiniz alanlardan biri geçersiz. Sebep alan bazında details.errors[] içindedir; oradaki field değerine bakın.

UNAUTHENTICATED

Kimlik doğrulanamadı. Authorization: Bearer … başlığı yok, token geçersiz ya da süresi dolmuş. Token ömrü tipik olarak 5 dakikadır — önbelleğe alıp expires_at'e göre yenileyin. → Kimlik Doğrulama

PERMISSION_DENIED

Token geçerli ama bu işlem için gereken kapsamı taşımıyor. Anahtarınıza tanımlı kapsamları kontrol edin.

auth.permission.forbidden

PERMISSION_DENIED ile aynı durum, granular kod biçiminde döner.

INVALID_SIGNATURE

İmza doğrulanamadı. En sık üç sebep:

1. Gövdesiz istekte Digest: satırını kanonik dizeye eklediniz — eklenmemeli. Token basma çağrısının kanonik dizesi dört satırdır.
2. Satır sırası ya da başlık yazımı farklı.
3. crypto.sign'ın ilk argümanı null değil — Ed25519'da hash algoritması belirtilmez.

→ Kanonik dize

NONCE_REPLAY

Bu X-Nonce daha önce kullanılmış. Nonce tek kullanımlıktır; her istek için yeni bir değer üretin (UUID uygundur).

IP_NOT_ALLOWED

İstek, anahtarınız için tanımlı izin listesinde olmayan bir IP'den geldi. Sunucunuzun çıkış IP'si değiştiyse (yeni deploy, NAT değişikliği) listeyi güncelleyin.

MERCHANT_SUSPENDED

Hesap askıya alınmış. Bu, istekle düzeltilebilecek bir durum değildir — destek ekibiyle iletişime geçin.

AUTH_REFRESH_REUSED

Bir yenileme jetonu ikinci kez kullanıldı ve oturum güvenlik gereği sonlandırıldı. Genellikle iki süreç aynı jetonu paylaştığında olur — token yenilemeyi tek bir yerde toplayın.

PRODUCT_NOT_ENABLED

Kimliğiniz doğrulandı, izniniz de yerinde — ama çağırdığınız uç bir ürüne ait ve o ürüne yetkiniz yok. Ürün, izinden ayrı bir eksendir: bir işlemi yapma izniniz olması, o ürünün hesabınızda açık olduğu anlamına gelmez.

İki ayrı koşul birden gerekir; hangisinin eksik olduğunu panelden görebilirsiniz:

Aboneliğiniz varken bu hatayı alıyorsanız neredeyse her zaman ikinci koşul eksiktir: API anahtarı bilinçli bir daraltmadır ve abonelik açıldığında mevcut anahtarlarınız kendiliğinden genişlemez.

PRODUCT_ENTITLEMENT_UNAVAILABLE

PRODUCT_NOT_ENABLED ile karıştırmayın. Bu kod "ürününüz yok" demez; "ürün yetkinizi şu anda doğrulayamıyoruz" der. HTTP durumu 503'tür ve geçicidir.

Yetkilendirme kapısı fail-closed çalışır: doğrulayamadığımız bir yetkiyle isteği geçirmeyiz. Yapmanız gereken, hesabınızda bir değişiklik değil — yeniden denemektir. Üstel geri çekilmeli (exponential backoff) bir yeniden deneme yeterlidir.

payment.amount.field_removed

Ödeme isteğinde kaldırılmış bir tutar alanı (price ya da paidPrice) gönderdiniz. Ödeme uçlarında tek tutar alanı amount'tır: kuruş cinsinden tam sayı, en az 1. Gönderdiğiniz kaldırılmış alanlar details.fields içinde, varsa diğer alan hataları details.errors[] içinde döner.

• amount sepet toplamıdır: alıcının ödediği ürün ve hizmet bedeli, vade farkı hariç. basketItems gönderirseniz kalemlerin price toplamı amount'a eşit olmalıdır. Kalemdeki price alanı kalem tutarıdır ve yerinde durur.
• Vade farkını göndermezsiniz. Taksitte sistem vade farkını bağlayıcı taksit teklifinden hesaplar ve çekilen tutara ekler.

→ Checkout Formu · Kart — 2D · Taksit & BIN

payment.method.disabled

Seçtiğiniz ödeme yöntemi işletmenizin panelindeki form ayarlarında kapalı. Panelde kapatılan yöntem her kanalda kapalıdır: Checkout Formu'nda gösterilmez, GET /payments/methods listesinde yer almaz ve POST /payments/direct/payment ile de başlatılamaz. HTTP durumu 422'dir; ödeme başlamadan reddedilir, para hareket etmez.

• Yöntemi kullanmak istiyorsanız panelde Ödeme Formu Ayarları'ndan açın.
• Hangi yöntemlerin açık olduğunu GET /payments/methods ile okuyun.

→ Payment · Checkout Formu — Payment

payment.method.unknown

Gönderdiğiniz yöntem kodu tanınmıyor. HTTP durumu 400'dür. Yöntem kodları büyük harfle yazılır (CARD, WALLET, MOBILE_BILLING …); başka bir yönteme ya da karta çevrilmez.

• POST /payments/direct/payment isteğinde paymentMethod alanına geçerli bir kod gönderin.
• GET /payments/methods?paymentMethod= süzgecinde tanınmayan, küçük harfle yazılmış, boş ya da tekrarlanan değer bu kodu alır. Yanıtta details.field paymentMethod'dur; tanınan bütün kodlar details.allowed listesindedir.

→ Yöntemleri Listeleme · Payment

payment.provider.required

Bu yöntemde sağlayıcıyı alıcı seçer (providerSelectionMode: BUYER) ve hesabınıza birden fazla sağlayıcı bağlı, ama istekte providerCode yok. HTTP durumu 400'dür; ödeme başlamadan reddedilir.

• Bağlı sağlayıcıların kodları details.boundProviderCodes içindedir.
• Sağlayıcıları alıcıya gösterin ve seçtiği sağlayıcının kodunu yöntem bloğunda providerCode ile gönderin (ör. wallet.providerCode).

→ Yöntemleri Listeleme › Sağlayıcı seçimi · Cüzdanla Öde

payment.provider.none_eligible

Bu yöntemde sağlayıcıyı platform seçer (providerSelectionMode: PLATFORM), istekte providerCode yok ve hesabınıza bağlı sağlayıcıların hiçbiri bu ödemeyi karşılamıyor. HTTP durumu 422'dir. Ödeme başlatılmaz ve tutar çekilmez.

Her sağlayıcının sonucu details.candidates[] içindedir:

• Sonuçlardan biri UNAVAILABLE ya da NOT_CHECKED ise aynı isteği daha sonra tekrar deneyebilirsiniz.
• Sağlayıcıyı yöntem bloğunda providerCode ile kendiniz de seçebilirsiniz.
• Bütün sonuçlar INELIGIBLE ise alıcıya başka bir yöntem önerin.

→ Faturana Yansıt › Hiçbir sağlayıcı uygun değil · Yöntemleri Listeleme › Sağlayıcı seçimi

payment.provider.disabled_in_form

Seçilen sağlayıcı işletmenin Form Ayarları'nda yalnız formda kapatılmış. HTTP durumu 422'dir; ödeme başlamadan reddedilir ve para hareket etmez. Bu kod yalnız Checkout Formu yolunda döner.

• Checkout Formu alıcıya formda açık başka bir sağlayıcı ya da yöntem sunar.
• Sağlayıcıyı formda kullanmak istiyorsanız panelde Ödeme → Form Ayarları ekranında yöntemin Ödeme seçenekleri listesinden açın.
• Formda kapalı sağlayıcı GET /payments/methods listesinde görünür ve POST /payments/direct/payment ile kullanılabilir.

→ Checkout Formu — Payment › Sıra ve formda gösterilen sağlayıcılar

payment.method.selection_attempts_exhausted

Bu ödemede kart dışı yöntem seçimi deneme sınırına (3) ulaşıldı. HTTP durumu 409'dur; seçim yazılmaz, sağlayıcı çağrılmaz ve para hareket etmez.

• Sınır ödeme (sipariş) başınadır; aynı siparişin yeni denemeleri de aynı sayacı kullanır.
• Alıcı aynı siparişi kartla ödeyebilir.

→ Checkout Formu — Payment › Sağlayıcı seçimi

payment.checkout.order_locked

Siparişte parçalı ödeme sürüyor; sonuçlanmadan aynı siparişte tek kartla, kart dışı yöntemle ya da cüzdanla ödeme başlatılamaz. HTTP durumu 409'dur; ödeme kaydına dokunulmaz.

• Parçalı ödemenin sonuçlanmasını bekleyin. Parçalı ödeme başarısız olur, süresi dolar ya da alıcı vazgeçerse sipariş açık kalır ve başka bir yöntemle ödenebilir.

→ Parçalı Ödeme › Sipariş kilidi

split_pay.checkout.order_not_open

Siparişte başka bir ödeme başlamış ya da sipariş kapanmış; parçalı ödeme başlatılamaz. HTTP durumu 409'dur; parçalı ödeme yazılmaz ve kart çekilmez. Sebep details.reason içindedir:

→ Parçalı Ödeme › Sipariş kilidi

Parçalı ödeme kodları

Parçalı ödeme uçlarının (POST /payments/split, POST /payments/split/{splitPaymentId}/refund ve Checkout Formu'nun parçalı ödeme uçları) kodları. Ayrıntı her zaman details içindedir.

Doğrulama

Parçalı ödeme başlamadan reddedilir; hiçbir parçadan para çekilmez. HTTP durumu 422'dir. details.legIndex ya da details.index sorunlu parçanın sırasını (0'dan başlar) gösterir.

Adımlar, devam bağlantısı ve devam sayfası

split_pay.step.not_allowed için details.reason:

İade

→ Parçalı Ödeme › Hatalar

Diğer sık görülen kodlar

Bunlar docsUrl taşımaz ama sık karşılaşılır:

Fraud uçlarının tüm hata kodları, kota başlıkları ve yeniden deneme kuralları: Fraud — Hatalar ve Yeniden Deneme.

Gizlilik

İlgili

• Kimlik Doğrulama — imzalı istek hataları
• API'ye Genel Bakış — zarf ve idempotency
• Webhook'lar — teslimat hataları ayrı bir mekanizmadır