Hatalar

PrimeAPI isteklerine verilen yanıtlarda tüm uç noktalar bir ApiResult<T> zarfı kullanır. Başarılı sonuçlarda result alanı dolu, error boş olur. Hata durumlarında HTTP 200 döndürülebilir ancak error alanı dolar.

Yanıt zarfı

Hata türleri

PrimeAPI’de iki ana hata kaynağı vardır:

V4 mobil imza ve fingerprint hata kodları

Bu sözleşme PAdES Mobile V4, CAdES Mobile V4, XAdES Mobile V4 ve ortak V2 fingerprint güncellemesini içeren API sürümü için geçerlidir. Dokümanın güncellenmiş olması ilgili API ortamının deploy edildiği anlamına gelmez; ortam sürümünü doğrulayın. V1/V2 imza endpoint'lerinin aynı kodları ürettiği varsayılmamalıdır.

UNKNOWN_CLIENT servis hesabı/parola hatası değildir. USER_CANCEL, operatörün bildirdiği sonuçtur; kullanıcının cihazda yaptığı fiziksel eylemin bağımsız doğrulaması değildir. Bu kodlardan geçmişteki her genel hatanın veya HTTP 524'ün kullanıcı iptali olduğu sonucu çıkarılamaz.

EXPIRED_TRANSACTION, OPERATOR_TIMEOUT ve OPERATOR_UNAVAILABLE için ilgili V4 API iyileştirmesinin dağıtılmış olması gerekir. Eski sürümler bu durumlarda SIGNING_FAILED dönebilir. HTTP timeout bir telefon iptali değildir. V4 HTTP istemcisinin süresi 150 saniye, operatöre verilen süre 120 saniyedir; reverse proxy ve toplam API süresi için garanti verilmez.

{
  "result": {
    "isSuccess": false,
    "operationId": "22222222-2222-2222-2222-222222222222"
  },
  "error": "Mobil imza işlemi iptal edildi.",
  "errorCode": "USER_CANCEL"
}

{
  "result": {
    "isSuccess": false,
    "operationId": "22222222-2222-2222-2222-222222222222"
  },
  "error": "Bu telefon numarası için operatörde mobil imza kaydı bulunamadı. Numaranızı ve seçilen operatörü kontrol edin.",
  "errorCode": "UNKNOWN_CLIENT"
}

{
  "result": { "fingerPrint": null },
  "error": "Bekleme süresi içinde parmak izi bulunamadı.",
  "errorCode": "FINGERPRINT_TIMEOUT"
}

displayLanguage: "en" için iptal mesajı Mobile signing was cancelled., abonelik mesajı No mobile signature registration was found for this phone number with the operator. Check the phone number and selected operator. olur. Fingerprint mesajı Fingerprint could not be found within the waiting period. şeklindedir. Kararları çevrilen mesaj metni yerine kod ve işlem sonucuna göre alın.

Mevcut result ve error alanları korunur. Yeni alanları reddeden katı istemci modellerine opsiyonel errorCode ekleyin; bilinmeyen kodlar için genel hata yolu bırakın. Ham SOAP veya kimlik bilgileri bu hata yanıtlarına eklenmez. Kodlar yeni bir veritabanı kolonu değildir; geçmiş kayıtlar ve başka sorgu endpoint'leri aynı kodları döndürmeyebilir.

İmza hatasında bekleyen fingerprint sorgusunu mümkünse iptal edin. Fingerprint'in bulunması başarı kanıtı değildir; geç gelen yanıt sonlandırılmış işlemi tekrar aktif hale getirmemelidir. Fingerprint sorgusunda imza isteğinin girişindeki dosya işlem kimliğini, başarılı imzayı indirirken ise imza yanıtındaki yeni işlem kimliğini kullanın.

Yaygın uygulama hataları (mesajlar)

Bu bölüm, controller’larda en sık görülen hataların kısa bir listesidir. Metinler birebir veya yakın olabilir; sürümlere göre küçük farklılıklar gösterebilir.

Örnek hata yanıtı

{
  "result": null,
  "error": "user-not-found"
}

{
  "result": null,
  "error": "System error occurred. Please contact support. Ref: 2025-12-18T10:15:30Z"
}

İyileştirme önerileri