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": {}
}
]
}
}
| Alan | Açıklama |
|---|---|
errorMessage | Makine tarafından okunabilen hata kodu. Hata işleme mantığınızda bunu kullanın. |
errorType | Hata kategorisi: FIELD (bir alan geçersiz, bkz. errorField), FORM (isteğin tamamı) veya GENERAL. |
errorId | Bu 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. |
errorField | Hatanın ilgili olduğu istek alanı, varsa. |
params | Hatanın ek parametreleri, varsa. |
requestParams | Hatayla 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.
errorMessage | Anlamı |
|---|---|
missingRequestParameter | Zorunlu bir parametre eksik. |
methodArgumentTypeMismatch | Bir 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. |
badParametersException | Bir veya daha fazla parametre geçersiz. |
badFormatAmountException | Tutarın biçimi geçersiz. |
notEnoughMoneyException | Kaynak cüzdanda yeterli bakiye yok. |
limitPerTransactionException | Tutar, 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. |
walletCurrencyIncorrectException | Cüzdanın para birimi istekle eşleşmiyor. |
recipientDoesNotExistException | Alıcının hesabı mevcut değil. |
paymentMethodNotAvailableForMerchantApi | Ödeme yöntemi API'niz için kullanılamıyor. |
resourceNotFound | Uç nokta mevcut değil. |
attemptsHaveEndedException | Hesap saatlik istek sınırını doldurdu. Bkz. İstek sınırı. |
tryAgainAfterAWhile | Veriler geçici olarak kilitli. Daha sonra yeniden deneyin. |
serviceTemporaryUnavailable | Bir hizmet geçici olarak kullanılamıyor. Daha sonra yeniden deneyin. |
internalServerError | Beklenmeyen sunucu hatası. |
HTTP durum kodları
| Durum | Anlamı |
|---|---|
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. |
401 | Kimlik 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ı. |
405 | Uç nokta bu HTTP yöntemini desteklemiyor (httpMethodNotAllowed). |
409 | Veriler geçici olarak kilitli (tryAgainAfterAWhile). |
415 | İsteğin Content-Type değeri desteklenmiyor (unknownContentType). |
500 | Beklenmeyen sunucu hatası (internalServerError). |
503 | Bir 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
errorIddeğerini günlüğe kaydedin. - Düzeltilmesi gereken alanı bulmak için
errorFielddeğerine bakın. 401aldığı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
orderIddeğerinizle arayın. Bkz. Ödeme siparişi sorgulama.sciNamegönderirseniz Volet.com, o Hosted Checkout için aynıorderIdile oluşturulan ikinci faturayı reddeder.
Bir ödemenin oluşturulup oluşturulmadı ğı hâlâ belirsizse yeniden göndermeden önce destek ekibiyle iletişime geçin.