Hata Kodları

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

{
  "status": "failure",
  "code": "physical_pos.input.text_invalid",
  "message": "Metin boş olamaz ve görünmez ya da biçimlendirme karakteri içeremez.",
  "statusCode": 400,
  "requestId": "00000000-0000-0000-0000-000000000000",
  "details": { "field": "name", "reason": "forbidden_character" },
  "docsUrl": "https://docs.lunixi.com/tr/physical-pos/errors#physical_pos.input.text_invalid"
}

message isteğin diline göre Türkçe ya da İngilizce döner; aşağıdaki tablolardaki açıklamalar bu metinlerdir. → Hata Yönetimi › Dil seçimi
details her hatada bulunmaz. Bulunduğunda alan adını (field) ve sebebi (reason) taşıyabilir; physical_pos.validation.invalid hatasında ayrıntılar details.errors dizisindedir, her öğe { field, errors: [<sebep>] }. Değer hiçbir zaman details'e yazılmaz.
Aşağıdaki kodlarda yanıt docsUrl alanı taşır; bağlantı bu sayfada kodun satırına gider.
4xx hatalar yeniden denemeyle düzelmez. Yeniden denenebilir tek sınıf 503 ve diğer 5xx hatalardır. → Ortak Kurallar › Yeniden deneme

physical_pos.* kodları

İstek ve ortak kurallar

HTTP	`code`	Açıklama	Ne yapmalı
`400`	`physical_pos.validation.invalid`	Fiziksel POS isteğindeki alanlar geçersiz — gönderilen alanları kontrol edin.	`details.errors` içindeki alanı düzeltin.
`400`	`physical_pos.cursor.invalid`	Sayfalama imleci geçersiz; listeyi ilk sayfadan yeniden isteyin.	İlk sayfadan yeniden başlayın.
`400`	`physical_pos.idempotency.key_required`	Bu işlem için Idempotency-Key başlığı zorunludur.	`Idempotency-Key` başlığını ekleyin.
`400`	`physical_pos.idempotency.key_invalid`	Idempotency-Key 8-200 karakter, boşluksuz yazdırılabilir ASCII olmalı.	8–200 karakterlik, boşluksuz bir değer kullanın (ör. UUID).
`409`	`physical_pos.idempotency_mismatch`	Bu Idempotency-Key farklı bir istekle kullanılmış.	Yeni işlem için yeni bir anahtar kullanın.
`409`	`physical_pos.version_conflict`	Kayıt siz düzenlerken değişti; güncel hâlini alıp değişikliği yeniden yapın.	Kaydı yeniden okuyun, güncel `rowVersion` ile tekrar gönderin.
`400`	`physical_pos.input.code_invalid`	Kod biçimi geçersiz.	Kodu `A-Z`, `0-9`, `.`, `_`, `-` ile yazın; kapalı kümeli alanlarda listedeki bir değeri gönderin.
`400`	`physical_pos.input.text_invalid`	Metin boş olamaz ve görünmez ya da biçimlendirme karakteri içeremez.	`details.field` ve `details.reason`'a bakın; metni düzeltin.
`400`	`physical_pos.input.ref_invalid`	Referans değeri geçersiz: boşluksuz, yazdırılabilir ASCII olmalı.	Değeri izin verilen karakterlerle yazın.
`400`	`physical_pos.input.reason_code_invalid`	Sebep kodu geçersiz.	İşleme uygun bir gerekçe kodu gönderin.
`400`	`physical_pos.input.vendor_code_invalid`	Üretici kodu geçersiz.	Katalogdaki üretici kodunu kullanın.
`400`	`physical_pos.input.virtual_serial_invalid`	Sanal seri numarası geçersiz.	Yalnız `A-Z` ve `0-9` kullanın, en çok 64 karakter.
`400`	`physical_pos.input.bank_terminal_number_invalid`	Banka üye işyeri ya da terminal numarası geçersiz (yalnız büyük harf ve rakam).	MID ve TID'yi `A-Z` ve `0-9` ile, en çok 32 karakter yazın.
`404`	`physical_pos.record.reference_not_found`	Bağlanmak istenen kayıt bulunamadı.	Gönderdiğiniz kimlikleri kontrol edin.
`409`	`physical_pos.record.already_exists`	Bu kayıt zaten var.	Kaydı okuyun; aynı isteği yeni bir anahtarla tekrarlamayın.
`409`	`physical_pos.record.field_immutable`	Bu alan oluşturulduktan sonra değiştirilemez.	Bu alanı değiştirmeyin; gerekirse yeni kayıt oluşturun.
`409`	`physical_pos.record.interval_conflict`	Kayıt aynı anda başka bir istekle değişti; güncel hâlini okuyup yeniden deneyin.	Kaydı yeniden okuyup tekrar deneyin.
`400`	`physical_pos.input.empty_patch`	Güncellenecek alan yok.	Değiştirmek istediğiniz en az bir alanı gönderin.
`400`	`physical_pos.input.filter_invalid`	Liste süzgeci geçersiz; `details.field` alanındaki değeri düzeltin.	`details.field`'da adı geçen süzgeci düzeltin.
`400`	`physical_pos.input.serial_invalid`	Cihaz seri numarası geçersiz.	Seri numarasını üreticinin biçimiyle yazın.
`400`	`physical_pos.input.channel_variant_invalid`	Entegrasyon kanalı varyantı geçersiz.	Yalnız `A-Z`, `0-9` ve `_` kullanın, en çok 32 karakter.

Kimlik ve ortam

HTTP	`code`	Açıklama	Ne yapmalı
`403`	`physical_pos.environment.test_key_read_only`	TEST API anahtarı fiziksel POS kayıtlarını yalnız okuyabilir; değişiklik için LIVE anahtarı ya da paneli kullanın.	Fiziksel POS yazma isteklerinin hepsi için canlı anahtarı ya da paneli kullanın.
`400`	`physical_pos.input.environment_invalid`	Ortam bilgisi geçersiz: API anahtarıyla istekte ortam gönderilmez; panel yalnız canlı ortamla çalışır.	İstekte `environment` göndermeyin; ortamı anahtarınız belirler.
`403`	`physical_pos.auth.scope_missing`	Bu fiziksel POS işlemi için gerekli yetki yok.	Anahtara gereken kapsamı ekleyin.
`403`	`physical_pos.auth.organization_missing`	İsteğin ait olduğu organizasyon doğrulanamadı.	Anahtarın geçerli olduğunu kontrol edin; sürerse destekle iletişime geçin.
`403`	`physical_pos.auth.environment_missing`	İsteğin ortamı doğrulanamadı.	Anahtarın geçerli olduğunu kontrol edin; sürerse destekle iletişime geçin.
`403`	`physical_pos.auth.actor_missing`	İşlemi yapan kullanıcı doğrulanamadı.	Anahtarın geçerli olduğunu kontrol edin; sürerse destekle iletişime geçin.

Mağaza ve kasa

HTTP	`code`	Açıklama	Ne yapmalı
`404`	`physical_pos.store.not_found`	Mağaza bulunamadı.	Mağaza kimliğini kontrol edin.
`404`	`physical_pos.register.not_found`	Kasa bulunamadı.	Kasa kimliğini kontrol edin.
`409`	`physical_pos.store.code_taken`	Bu kodla bir mağaza zaten var (arşivli mağazalar da kodlarını korur).	Başka bir kod seçin ya da arşivli mağazayı yeniden açın.
`409`	`physical_pos.store.external_ref_taken`	Bu dış referansla bir mağaza zaten var.	Başka bir `externalRef` kullanın.
`409`	`physical_pos.store.archived`	Mağaza arşivli; önce mağazayı yeniden açın.	Önce mağazayı yeniden açın.
`409`	`physical_pos.store.has_devices`	Cihaz atanmış mağaza arşivlenemez; cihazları başka bir mağazaya taşıyın, depoya alın ya da emekliye ayırın.	Cihazları başka mağazaya ya da kasaya taşıyın, depoya alın ya da emekliye ayırın.
`409`	`physical_pos.store.too_many_active_registers`	Mağazanın aktif kasası tek seferde arşivlenemeyecek kadar çok; önce kasaları arşivleyin.	Önce kasaları tek tek arşivleyin.
`409`	`physical_pos.store.invalid_transition`	Mağazanın durumu bu şekilde değiştirilemez.	Mağazanın güncel durumunu okuyun.
`409`	`physical_pos.store.has_active_registers`	Aktif kasası olan mağaza arşivlenemez; önce kasaları arşivleyin.	Önce kasaları arşivleyin.
`409`	`physical_pos.store.has_open_assignments`	Cihaz ataması açık olan mağaza arşivlenemez; cihazları başka bir mağazaya taşıyın, depoya alın ya da emekliye ayırın.	Cihazları başka mağazaya ya da kasaya taşıyın, depoya alın ya da emekliye ayırın.
`409`	`physical_pos.register.code_taken`	Bu mağazada bu kodla bir kasa zaten var.	Bu mağazada başka bir kasa kodu seçin.
`409`	`physical_pos.register.archived`	Kasa arşivli; önce kasayı yeniden açın.	Önce kasayı yeniden açın.
`409`	`physical_pos.register.has_devices`	Cihaz atanmış kasa arşivlenemez; cihazları başka bir mağaza ya da kasaya taşıyın, depoya alın ya da emekliye ayırın.	Cihazları başka mağazaya ya da kasaya taşıyın, depoya alın ya da emekliye ayırın.
`409`	`physical_pos.register.invalid_transition`	Kasanın durumu bu şekilde değiştirilemez.	Kasanın güncel durumunu okuyun.
`409`	`physical_pos.register.has_open_assignments`	Cihaz ataması açık olan kasa arşivlenemez; cihazları başka bir mağaza ya da kasaya taşıyın, depoya alın ya da emekliye ayırın.	Cihazları başka mağazaya ya da kasaya taşıyın, depoya alın ya da emekliye ayırın.
`409`	`physical_pos.register.store_archived`	Arşivli mağazanın kasası açılamaz; önce mağazayı yeniden açın.	Önce mağazayı yeniden açın.
`409`	`physical_pos.device_assignment.target_archived`	Arşivli mağazaya ya da kasaya cihaz atanamaz.	Etkin bir mağazaya ya da kasaya atayın.

Mantıksal terminal, banka satırı ve cihaz bağı

HTTP	`code`	Açıklama	Ne yapmalı
`404`	`physical_pos.terminal.not_found`	Terminal bulunamadı.	Terminal kimliğini ve anahtarınızın ortamını kontrol edin.
`409`	`physical_pos.terminal.code_taken`	Bu kodla bir terminal zaten var.	Bu ortamda başka bir terminal kodu seçin.
`409`	`physical_pos.terminal.vendor_ref_taken`	Bu üretici terminal referansıyla açık bir terminal zaten var.	Değeri kullanan terminali kontrol edin.
`409`	`physical_pos.terminal.virtual_serial_taken`	Bu sanal seriyle açık bir terminal zaten var.	Değeri kullanan terminali kontrol edin.
`409`	`physical_pos.terminal.closed`	Terminal kapatılmış; değişiklik yapılamaz.	Kapatılmış terminal değiştirilemez; gerekirse yeni terminal oluşturun.
`400`	`physical_pos.terminal.vendor_required`	Bu işlem için terminalin üreticisi belirtilmiş olmalı.	Terminale önce üretici atayın ya da `vendorCode` gönderin.
`400`	`physical_pos.device.vendor_unknown`	Cihaz üreticisi tanınmıyor.	Katalogdaki etkin bir üreticinin kodunu kullanın.
`400`	`physical_pos.terminal.device_vendor_mismatch`	Terminal ile cihaz farklı üreticilere ait; bağlanamaz.	Terminalle aynı üreticinin cihazını kullanın ya da cihazın üreticisini atayın.
`409`	`physical_pos.logical_terminal.invalid_transition`	Terminalin durumu bu şekilde değiştirilemez.	Terminalin güncel durumunu okuyun.
`404`	`physical_pos.acquirer.not_found`	Banka kaydı bulunamadı.	Banka satırı kimliğini ve ortamı kontrol edin.
`409`	`physical_pos.acquirer.duplicate`	Bu banka ve terminal numarasıyla bir kayıt zaten var.	Mevcut satırı kullanın ya da yeniden etkinleştirin.
`400`	`physical_pos.acquirer.currency_invalid`	Para birimi listesi geçersiz: ISO 4217 kodları, tekrarsız, en çok 16.	Listeyi tekrarsız ISO 4217 kodlarıyla, en çok 16 kod olarak gönderin.
`409`	`physical_pos.terminal.link_conflict`	Cihaz başka bir terminale bağlı; önce o bağ kapanmalı.	Önce cihazın diğer terminaldeki bağını çözün.
`409`	`physical_pos.terminal.device_already_linked`	Cihaz zaten bu terminale bağlı.	İşlem gerekmez; terminali okuyun.
`409`	`physical_pos.terminal.device_not_linked`	Terminale bağlı cihaz yok.	İşlem gerekmez; terminali okuyun.
`409`	`physical_pos.terminal.environment_mismatch`	Terminal ile cihazın ortamı (test / canlı) aynı olmalı.	Terminalle aynı ortamdaki bir cihaz kullanın.

Cihazlar

HTTP	`code`	Açıklama	Ne yapmalı
`404`	`physical_pos.device.not_found`	Cihaz bulunamadı.	Cihaz kimliğini ve ortamını kontrol edin.
`404`	`physical_pos.device_model.not_found`	Cihaz modeli bulunamadı.	Katalogdaki bir model kimliğini kullanın.
`400`	`physical_pos.device.model_vendor_mismatch`	Cihaz modeli seçilen üreticiye ait değil.	`vendorCode` ile aynı üreticinin modelini seçin.
`409`	`physical_pos.device.model_deprecated`	Bu cihaz modeli kullanımdan kaldırılmış; yeni cihaz eklenemez.	Etkin bir model seçin.
`400`	`physical_pos.device.app_mode_invalid`	Uygulama modu yalnız uygulamalı entegrasyon kanallarında (APP2APP, LOCAL_REST) seçilebilir.	`appMode`'u yalnız `APP2APP` ya da `LOCAL_REST` kanalında gönderin.
`409`	`physical_pos.device.serial_taken`	Bu seri numarasıyla kayıtlı bir cihazınız zaten var.	Bu seriyle kayıtlı cihazınızı kullanın.
`409`	`physical_pos.device.external_ref_taken`	Bu dış referans başka bir cihazınızda kullanılıyor.	Başka bir `externalRef` kullanın.
`409`	`physical_pos.device.already_assigned`	Cihaz zaten bu mağaza ve kasaya atanmış.	İşlem gerekmez; cihazı okuyun.
`409`	`physical_pos.device.not_assigned`	Cihaz herhangi bir mağazaya atanmış değil.	İşlem gerekmez; cihazı okuyun.
`409`	`physical_pos.device.invalid_transition`	Cihazın durumu bu şekilde değiştirilemez.	Cihazın güncel durumunu okuyun.
`409`	`physical_pos.device.ownership_unverified`	Sahipliği doğrulanmamış cihaz etkinleştirilemez.	Sahipliği doğrulanmamış cihazın durumu değiştirilemez.
`409`	`physical_pos.device.identity_active`	Cihazın etkin kimlik anahtarı ya da açık aktivasyon kodu var; önce kimliği iptal edin.	Cihazın etkin kimliği varken emekliye ayrılamaz.
`409`	`physical_pos.device.retired`	Cihaz emekliye ayrılmış; bu işlem yapılamaz.	Emekli cihaz değiştirilemez; başka bir cihaz kullanın.

Sunucu

HTTP	`code`	Açıklama	Ne yapmalı
`503`	`physical_pos.service.busy`	Kayıt şu anda başka bir işlemle meşgul; kısa bir süre sonra yeniden deneyin.	Kısa bir beklemeden sonra aynı istekle yeniden deneyin.
`503`	`physical_pos.dependency.unavailable`	Bağımlı servis şu anda yanıt vermiyor; lütfen biraz sonra yeniden deneyin.	Geri çekilerek yeniden deneyin.
`503`	`physical_pos.service.not_configured`	Fiziksel POS hizmeti şu anda kullanılamıyor. Lütfen daha sonra tekrar deneyin.	Geri çekilerek yeniden deneyin.
`500`	`physical_pos.internal.integrity`	İşlem şu anda tamamlanamıyor. Lütfen daha sonra tekrar deneyin.	Geri çekilerek yeniden deneyin; sürerse `requestId` ile destekle iletişime geçin.
`500`	`physical_pos.gateway.response_invalid`	Fiziksel POS hizmetinden beklenmeyen yanıt alındı. Lütfen daha sonra tekrar deneyin.	Geri çekilerek yeniden deneyin; sürerse `requestId` ile destekle iletişime geçin.

Başka bir organizasyona ait kayıt ile olmayan kayıt aynı 404 cevabını alır; biçim dışı kimlikler de aynı cevabı alır. Bu, kayıtların varlığının dışarıdan anlaşılmasını önler.

Platform kodları

Bu kodlar imza, ürün, kapsam, doğrulama ve oran sınırı katmanlarından gelir ve bütün ürünlerde aynıdır:

HTTP	`code`	Ne zaman
`400`	`VALIDATION_ERROR`	Tanımlanmamış alan ya da sorgu parametresi; değer kümesi dışında süzgeç; yanlış tip.
`401`	`AUTH_HEADERS_MISSING`, `INVALID_KID`, `INVALID_SIGNATURE`, `NONCE_REPLAY`, `INVALID_DATE`, `DIGEST_MISSING`, `INVALID_DIGEST`	İstek imzası eksik ya da geçersiz. → Kimlik Doğrulama ve Kapsamlar
`403`	`IP_NOT_ALLOWED`, `MERCHANT_SUSPENDED`	İstek anahtarın IP izin listesi dışından geldi ya da hesabınız aktif değil.
`403`	`PRODUCT_NOT_ENABLED`	Anahtarda Fiziksel POS ürünü (`PHYSICAL_POS`) yok.
`403`	`API_INSUFFICIENT_SCOPE`	Anahtarda ucun kapsamı yok. → Kapsamlar
`429`	`RATE_LIMITED`	Oran sınırı aşıldı; `Retry-After` kadar bekleyin. → Oran sınırı
`503`	`PRODUCT_ENTITLEMENT_UNAVAILABLE`	Ürün yetkiniz şu an doğrulanamadı; geri çekilerek yeniden deneyin.
`503`	`gateway.downstream_unavailable`	Hizmete şu an ulaşılamıyor; geri çekilerek yeniden deneyin.
`504`	`gateway.downstream_timeout`	Hizmet zamanında yanıt vermedi; geri çekilerek yeniden deneyin. Oluşturma isteklerinde aynı `Idempotency-Key`'i kullanın.

Kodların ayrıntısı: Hata Yönetimi › Kod sözlüğü.

Genel Bakış Sayaçları