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ı

Name
result
Description
İstenen değerin kendisi (tipi uç noktaya göre değişir).
Name
error
Type
string
Description
Hata durumunda açıklama mesajı. Boş ise işlem başarılıdır.

Hata türleri

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

Name
ApplicationError
Description
İş kuralı/validasyon hataları. Örn. zorunlu alanların eksikliği, yetkisizlik, kaynak bulunamaması.
Name
SystemError
Description
Beklenmeyen durumlar/istisnalar. Sunucu tarafından yakalanıp error içine özetlenir.

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.

Name
UserId boş
Description
Yetkilendirme kimliği (user_id claim) yok veya geçersiz.
Name
empty-request-id
Description
RequestId 21 karakter değil ya da boş.
Name
user-not-found
Description
Kullanıcı bulunamadı veya pasif/silinmiş.
Name
ApiUser bulunamadı.
Description
İlgili kullanıcıya ait ApiUser kaydı yok.
Name
ApiUser CoreApiV2 kullanımı için uygun değil.
Description
ApiUser tipi bu uç noktayı kullanmaya uygun değil.
Name
users-organization-not-found
Description
Kullanıcının organizasyon kaydı bulunamadı.
Name
Lisans süresi bitmiş.
Description
Organizasyon lisansı sona ermiş (CoreApiFile.UploadFile).
Name
Dosya bulunamadı.
Description
operationId ile ilişkili çıktı dosyası mevcut değil.
Name
Dosya silinmiş.
Description
İlgili işlem silinmiş durumda (DeletedDate dolu).
Name
Farklı kullanıcıya ait işlem.
Description
İşlem sahibinin kullanıcısı ile istek yapan kullanıcı farklı.
Name
Geçersiz uploadsessionid. / Yükleme oturumu bulunamadı / geçersiz
Description
Parça/parça yüklemede yanlış veya süresi dolmuş oturum.
Name
Eksik header. / Geçersiz chunkindex. / Parça boyutu geçersiz.
Description
Chunk upload sırasında eksik ya da hatalı başlık/değer.
Name
Birleştirilmiş dosya boyutu beklenenden farklı.
Description
Parça birleştirme sonrası dosya boyutu doğrulanamadı.
Name
Önimzalı doküman okunamadı.
Description
signStepThree aşamasında dosya okunamadı.
Name
İmzalama işleminde hata oluştu.
Description
İmzalama sırasında beklenmeyen durum.
Name
İmzalı veri boş olamaz. / İşlem şifresi geçersiz.
Description
signStepThree giriş doğrulamaları (SignedData/KeyId/KeySecret).

Örnek hata yanıtı

Application error

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

System error

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

İyileştirme önerileri

Name
İstek doğrulaması
Description
RequestId (21 karakter) ve dil (displayLanguage) alanlarını doldurun.
Name
OperationId zinciri
Description
Her adımda dönen en güncel operationId değerini izleyin.
Name
Retry/idempotency
Description
Chunk upload parça yüklemesi idempotenttir; aynı parçayı tekrar göndermek kabul edilebilir.
Name
Log korelasyonu
Description
Hata mesajlarını operationId ve requestId ile birlikte kaydedin.