Hatalar

HTTP durum kodları

Kod	Anlamı	İmzalı
200	İstek işlendi. Sonuç result.successful alanındadır; sağlayıcının reddettiği bir ödeme, iade ya da kart saklama da 200 ile ve successful: false olarak döner.	evet
401	X-Api-Key ya da X-Signature geçersiz. İstek işlenmedi.	hayır
403	Çalışma alanı şu an işlem yapamıyor ya da planı bu ucu kapsamıyor. İstek işlenmedi.	evet
422	Gövde doğrulamadan geçmedi. İstek işlenmedi; sağlayıcıya bir şey gönderilmedi.	evet

Yanıtı okurken önce durum koduna bakın. 4xx yanıtlarının bir kısmı imzalıdır, ancak imzalı olması onu bir işlem sonucuna çevirmez.

Bu dört kod dışında bir yanıt (ör. 5xx) yukarıdaki result biçiminde olmayabilir.

Hata yanıtı

{
  "result": {
    "successful": false,
    "message": "Çalışma alanınızın planı bu özelliği kapsamıyor."
  }
}

401

result.message	Neden
Geçersiz API anahtarı.	X-Api-Key eksik ya da adresteki çalışma alanına ait değil.
İmza doğrulanamadı.	X-Signature eksik ya da gövdeyle tutmuyor.

403

result.message	Neden
Çalışma alanınızın ödenmemiş bakiyesi bulunduğu için işlem yapılamıyor.	Çalışma alanının vadesi geçmiş bakiyesi var.
Çalışma alanınızın plan ödemesi alınamadığı için işlem yapılamıyor.	Plan ödemesi alınamadı.
Çalışma alanınızın geçerli bir planı bulunmadığı için işlem yapılamıyor.	Geçerli plan yok.
Çalışma alanınızın planı bu özelliği kapsamıyor.	Plan bu ucu kapsamıyor: order-payment (siparişler), subscription-payment (abonelikler), save-card, saved-cards, default-saved-card, delete-saved-card (kayıtlı kartlar).

İlk üç durum bütün uçlar için geçerlidir.

Doğrulama hataları (422)

{
  "result": {
    "successful": false,
    "message": "Tutar 100 veya 100.10 biçiminde olmalıdır; kuruş basamağı noktayla ayrılır.",
    "errors": {
      "transaction.amount": [
        "Tutar 100 veya 100.10 biçiminde olmalıdır; kuruş basamağı noktayla ayrılır."
      ]
    }
  }
}

Alan	Açıklama
result.message	İlk hatanın özeti.
result.errors	Alan yolu (ör. transaction.amount, order.items.0.channel_reference) → mesaj listesi.

Doğrulama hatası alan istek işlenmez. Alanı düzeltip isteği yeniden gönderebilirsiniz.

Bazı iş kuralları da 422 olarak ilgili alanda döner; örneğin iade edilemeyen bir ödeme transaction.token, kart saklamayan bir ödeme hesabı payment_provider_token alanında reddedilir. Uca özel mesajlar her uç sayfasının Hatalar bölümündedir.

Ağ hataları

İstek gönderildikten sonra yanıt alınamadıysa (zaman aşımı, bağlantı kopması) işlemin gateway'de gerçekleşip gerçekleşmediği bilinmez. Bu durumda yanıttaki transaction.token da alınmamıştır ve API'de bir ödemeyi channel_reference ile sorgulayan bir uç yoktur.

API'de idempotency anahtarı bulunmaz; aynı ödeme isteğini tekrar göndermek yeni bir ödeme denemesidir.

SDK istisnaları

PHP, Java	Node.js, Python	Durum
ValidationException	ValidationError	422. errors alanı result.errors'tır.
AuthenticationException	AuthenticationError	401.
UnexpectedResponseException	UnexpectedResponseError	200, 401 ve 422 dışındaki her kod (403 dahil). Durum kodu istisnada bulunur.
SignatureException	SignatureError	200 yanıtının ya da webhook'un imzası tutmadı.
TransportException	TransportError	Gateway'e ulaşılamadı ya da yanıt okunamadı.

Hepsi OdemehubException (PHP, Java) ya da OdemehubError (Node.js, Python) sınıfından türer. 200 yanıtları istisna değildir; result.successful değerini kontrol edin.