Ana içeriğe geç

Hatalar

Bir istek başarısız olduğunda API, bir HTTP hata durumu ve data.errors içinde bir veya daha fazla hata bulunan yapılandırılmış bir yanıt döndürür.

Hata yanıtı​

{
"status": "error",
"data": {
"errors": [
{
"errorMessage": "resourceNotFound",
"errorType": "GENERAL",
"errorId": "3f69d9b6",
"errorDescription": "Resource not found",
"errorField": null,
"params": [],
"requestParams": {}
}
]
}
}
AlanAçıklama
errorMessageMakine tarafından okunabilen hata kodu. Hata işleme mantığınızda bunu kullanın.
errorTypeHata kategorisi: FIELD (bir alan geçersiz, bkz. errorField), FORM (isteğin tamamı) veya GENERAL.
errorIdBu hatanın tanımlayıcısı. Günlüğe kaydedin ve destek taleplerinizde belirtin.
errorDescriptionİnsanlar için açıklama. Program mantığında kullanmayın: metin değişebilir.
errorFieldHatanın ilgili olduğu istek alanı, varsa.
paramsHatanın ek parametreleri, varsa.
requestParamsHatayla ilgili istek parametreleri, varsa.

Sık karşılaşılan hata kodları​

Aşağıdaki liste, bir entegrasyonun genellikle ele alması gereken kodları kapsar. Liste eksiksiz değildir: bir yöntem başka kodlar da döndürebilir. Bilinmeyen bir errorMessage değerini genel hata olarak ele alın ve errorId değerini günlüğe kaydedin.

errorMessageAnlamı
missingRequestParameterZorunlu bir parametre eksik.
methodArgumentTypeMismatchBir parametrenin türü yanlış, örneğin sayı yerine metin.
httpMessageNotReadableİstek gövdesi geçerli bir JSON değil veya beklenen yapıya uymuyor.
unrecognizedFieldİstek gövdesi, yöntemin kabul etmediği bir alan içeriyor.
badParametersExceptionBir veya daha fazla parametre geçersiz.
badFormatAmountExceptionTutarın biçimi geçersiz.
notEnoughMoneyExceptionKaynak cüzdanda yeterli bakiye yok.
limitPerTransactionExceptionTutar, işlem başına sınırı aşıyor.
limitPerMonthExceptionİşlem aylık sınırı aşıyor.
walletDoesNotExistİstekteki cüzdan mevcut değil.
walletCurrencyIncorrectExceptionCüzdanın para birimi istekle eşleşmiyor.
recipientDoesNotExistExceptionAlıcının hesabı mevcut değil.
paymentMethodNotAvailableForMerchantApiÖdeme yöntemi API'niz için kullanılamıyor.
resourceNotFoundUç nokta mevcut değil.
attemptsHaveEndedExceptionHesap saatlik istek sınırını doldurdu. Bkz. İstek sınırı.
tryAgainAfterAWhileVeriler geçici olarak kilitli. Daha sonra yeniden deneyin.
serviceTemporaryUnavailableBir hizmet geçici olarak kullanılamıyor. Daha sonra yeniden deneyin.
internalServerErrorBeklenmeyen sunucu hatası.

HTTP durum kodları​

DurumAnlamı
400İstek hatalı biçimlendirilmiş, geçersiz parametreler içeriyor veya işlenemiyor. Bir sipariş veya başka bir varlık bulunamadığında da döndürülür.
401Kimlik doğrulama başlıkları eksik veya geçersiz ya da hesap saatlik istek sınırını doldurdu (attemptsHaveEndedException).
404İstenen uç nokta bulunamadı.
405Uç nokta bu HTTP yöntemini desteklemiyor (httpMethodNotAllowed).
409Veriler geçici olarak kilitli (tryAgainAfterAWhile).
415İsteğin Content-Type değeri desteklenmiyor (unknownContentType).
500Beklenmeyen sunucu hatası (internalServerError).
503Bir hizmet geçici olarak kullanılamıyor (serviceTemporaryUnavailable).

Hata kodunu yalnızca HTTP durumundan çıkarmayın: aynı durum farklı errorMessage değerleriyle gelebilir.

Hataları ele alma​

  • Her hatanın errorId değerini günlüğe kaydedin.
  • Düzeltilmesi gereken alanı bulmak için errorField değerine bakın.
  • 401 aldığınızda API adını, hesabın e-posta adresini, token'ı ve sunucunun UTC saatini kontrol edin.
  • API'nin işlem için izni yoksa veya sunucunuzun API'yi çağırmasına izin verilmiyorsa ödeme araçları bölümünde API'nin izinlerini ve IP beyaz listesini kontrol edin.

Güvenle yeniden deneme​

Hatalar iki gruba ayrılır:

  • Geçici — 409 (tryAgainAfterAWhile), 503 (serviceTemporaryUnavailable) ve zaman aşımları. Okuma ve doğrulama isteklerini, denemeler arasındaki bekleme süresini artırarak yeniden deneyin. İşlem veya fatura oluşturan istekler için aşağıya bakın.
  • Kalıcı — kimlik doğrulama ve parametre hataları. İsteği tekrarlamak yerine düzeltin.

Doğrulama istekleri (/api/withdrawal/validation/…) ve sorgular hiçbir şey oluşturmaz ve tekrarlanabilir.

Merchant API'de idempotency anahtarı yoktur. İşlem veya fatura oluşturan bir istek, API onu işledikten sonra zaman aşımına uğrayabilir veya hata verebilir; isteği tekrarlamak ikinci bir işlem veya fatura oluşturabilir. Zaman aşımı veya 5xx hatasından sonra, isteği tekrarlamadan önce oluşturulup oluşturulmadığını kontrol edin:

  • Ödemeler için işlem geçmişini ve cüzdan bakiyesini kontrol edin. Bkz. İşlem geçmişini sorgulama. Doğrulamadan geçen her ödeme isteği, önceki bir isteği tekrarlasa bile yeni bir işlem oluşturur.
  • Faturalar için siparişi kendi orderId değerinizle arayın. Bkz. Ödeme siparişi sorgulama. sciName gönderirseniz Volet.com, o Hosted Checkout için aynı orderId ile oluşturulan ikinci faturayı reddeder.

Bir ödemenin oluşturulup oluşturulmadığı hâlâ belirsizse yeniden göndermeden önce destek ekibiyle iletişime geçin.

  • Giriş — temel URL, kimlik doğrulama ve istek biçimi
  • Durumlar — işlem ve ödeme durumları