Hata kodları

Bu sayfada, Evrensel Ticaret Protokolü (UCP) kullanarak Google ile entegrasyon yaparken API yanıtlarınızda döndürmeniz gereken standart hata kodları özetlenmektedir. Tutarlı hata kodları, iletişimin net olmasını sağlar ve Google'ın farklı senaryoları uygun şekilde ele almasına yardımcı olur.

Bir işletme hatası oluştuğunda API'niz, tablodaki uygun code değerini içeren bir yanıt mesajı döndürmelidir. Bazı hata kodları için yanıttaki messages dizisinde belirli bir JSON yapısı kullanılması önerilir. Bu örnekler, tablonun altındaki Hata kodu örnekleri bölümünde verilmiştir. Bu örneklerde, istek veya yanıt nesnesindeki hatanın konumu hakkında daha ayrıntılı bilgi sağlamak için path alanını kullanmanız gerekir.

Hata İşleme

Hataların nasıl bildirileceği hata türüne bağlıdır:

• Protokol/Sunucu Hataları:

  • Hatalı biçimlendirilmiş istekler, kimlik doğrulama hataları veya sunucunun kullanılamaması gibi sorunlar için standart HTTP durum kodlarını (ör. istemci hataları için 4xx, sunucu hataları için 5xx) kullanın.
  • Ayrıntılar için UCP Spesifikasyonu'na bakın.

• İş mantığı hataları/uyarıları:

  • HTTP 200 OK durumunu döndürün. Bu, ödeme ağ geçidiniz 4xx veya 5xx hatası döndürse bile ödeme reddetme ve sahtekarlık reddetme işlemlerini içerir.
  • JSON yanıt gövdesindeki messages dizisinde sorunu açıklayın.
  • messages dizisindeki her nesne şunları içermelidir:
    • type: "error" veya "warning"
    • code: Bu kılavuzdaki standartlaştırılmış bir kod. "invalid" gibi genel veya tanınmayan kodlar kullanmayın.
    • content: İnsan tarafından okunabilen bir açıklama.
    • severity: type, "error" olduğunda zorunludur. Bu alan, hatanın nihai olup olmadığını açıkça belirtir (unrecoverable) veya hata kodunun kendisine güvenmek yerine alıcıdan sorunu düzeltmesini istemenize olanak tanır (recoverable).

Mesaj türleri: Hata ve uyarı

İleti dizisindeki type alanı, sorunun önem derecesini gösterir. UCP, iki temel tür tanımlar:

• error: İstenen işlemin tamamlanamadığını gösterir. Platformun veya kullanıcının işlem yapması ve tekrar denemesi gerekir. message-error specification bölümüne bakın.
  • Bir hatanın nihai olup olmadığı, hata code ile değil, severity alanı (unrecoverable veya recoverable) ile belirlenir.
• warning: İşlemin engellenmediğini ancak kullanıcıya iletilmesi gereken önemli bir durum olduğunu gösterir. Bu işlem süreci durdurmaz ancak önemli bağlam bilgileri sağlar. message-warning specification başlıklı makaleyi inceleyin.

Hata kodu referansı

Hata kodu örnekleri

Bu bölümde, belirli hata kodları için messages dizisine yönelik JSON örnekleri verilmiştir.

out_of_stock

Tek öğeli ödeme:

{
  "type": "error",
  "severity": "unrecoverable",
  "code": "out_of_stock",
  "content": "Unfortunately, the item 'Example Product 1' is out of stock."
}

Birden fazla öğe içeren ödeme:

Stokta olmayan belirli öğenin dizinini belirtmek için path alanını kullanın.

{
  "type": "error",
  "severity": "recoverable",
  "code": "out_of_stock",
  "path": "$.checkout.line_items[1]",
  "content": "The item 'Example Product 2' is out of stock. Remove it from your cart to continue."
}

quantity_invalid_limit_exceeded

{
  "type": "error",
  "severity": "recoverable",
  "code": "quantity_invalid_limit_exceeded",
  "path": "$.checkout.line_items[0].quantity",
  "content": "The requested quantity for 'Example Product 2' exceeds the maximum allowed limit of 5."
}

totals_changed

{
  "type": "warning",
  "code": "totals_changed",
  "path": "$.totals[2]",
  "content": "Shipping cost has changed."
}

missing_buyer_info

{
  "type": "error",
  "severity": "recoverable",
  "code": "missing_buyer_info",
  "path": "$.buyer.first_name",
  "content": "Missing buyer first name."
}

address_undeliverable

Sipariş düzeyinde kısıtlama (ör. posta kodu desteklenmiyor):

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_undeliverable",
  "content": "Delivery is not supported for the provided zipcode."
}

Öğe düzeyinde kısıtlama:

Belirli bir öğenin seçilen hedefe teslim edilemeyeceğini (ör. eyalete özgü yasaklar) belirtmek için path alanını kullanın.

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_undeliverable",
  "path": "$.checkout.line_items[1]",
  "content": "The item 'Example Product 2' cannot be delivered to the selected address."
}

address_unverifiable

Fatura adresi:

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_unverifiable",
  "path": "$.payment.instruments[0].billing_address",
  "content": "Invalid billing address. Update the address before trying again."
}

Sipariş karşılama adresi:

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_unverifiable",
  "path": "$.fulfillment.methods[0].destinations[0]",
  "content": "The fulfillment address couldn't be verified. Update the address and try again."
}

missing_billing_info

Fatura adresindeki eksik alanları belirtmek için path alanını kullanın.

{
  "type": "error",
  "severity": "recoverable",
  "code": "missing_billing_info",
  "path": "$.payment.instruments[0].billing_address.street_address",
  "content": "Missing billing street address."
}

identity_required

REST API'de bu hata, HTTP durum kodu 401 ile döndürülmelidir.

{
  "type": "error",
  "severity": "requires_buyer_review",
  "code": "identity_required",
  "content": "User identity is required to access order history."
}

insufficient_scope

REST API'de bu hata, HTTP durum kodu 403 ile döndürülmelidir.

{
  "type": "error",
  "severity": "requires_buyer_review",
  "code": "insufficient_scope",
  "content": "This operation requires scopes: dev.ucp.shopping.order:read, dev.ucp.shopping.order:manage"
}

Ödeme hataları

payment_declined

{
  "type": "error",
  "severity": "recoverable",
  "code": "payment_declined",
  "path": "$.payment.instruments[0]",
  "content": "Payment was declined by the issuer. Try a different payment method or contact your bank."
}

rejected_for_fraud

{
  "type": "error",
  "severity": "recoverable",
  "code": "rejected_for_fraud",
  "path": "$.payment.instruments[0]",
  "content": "The order was rejected due to suspected fraud. Try a different payment method."
}