Hata yanıtlarını işleme

Bu kılavuzda, Merchant API tarafından döndürülen hataların nasıl ele alınacağı açıklanmaktadır. Hata yanıtı yapısını ve kararlılığını anlamak, hatalardan otomatik olarak kurtulabilen veya kullanıcılara anlamlı geri bildirimler sağlayabilen sağlam entegrasyonlar oluşturmak için çok önemlidir.

Genel Bakış

Merchant API isteği başarısız olduğunda API, standart bir HTTP durum kodu (4xx veya 5xx) ve hatayla ilgili ayrıntıları içeren bir JSON yanıt gövdesi döndürür. Merchant API, hata ayrıntıları için AIP-193 standardını izler ve uygulamanızın belirli hata senaryolarını programatik olarak işlemesine olanak tanıyan, makine tarafından okunabilir bilgiler sağlar.

Hata yanıtı yapısı

Hata yanıtı; code, message ve status gibi standart alanları içeren bir JSON nesnesidir. Ayrıca, details dizisi de içerir. Hataları programatik olarak işlemek için details içinde @type değerinin type.googleapis.com/google.rpc.ErrorInfo olduğu bir nesne aramanız gerekir.

Bu ErrorInfo nesnesi, hatayla ilgili kararlı ve yapılandırılmış veriler sağlar:

  • domain: Hatanın mantıksal gruplandırması, genellikle merchantapi.googleapis.com.
  • metadata: Hatayla ilgili dinamik değerlerin bir haritası. Bu kanallar aşağıdakileri kapsar:
    • REASON: Tam hatanın belirli ve sabit bir tanımlayıcısı (ör. INVALID_NAME_PART_NOT_NUMBER, PERMISSION_DENIED_ACCOUNTS). Bu alan her zaman mevcuttur. Uygulama mantığınızda ayrıntılı hata işleme için bu alanı kullanın.
    • HELP_CENTER_LINK: Sorunu düzeltmek için ek bağlam ve talimatlar sağlar. Bu alan tüm hatalar için mevcut değildir ancak daha fazla bağlamın gerekebileceği hatalar için kapsamını zaman içinde genişletmeyi planlıyoruz.
    • Diğer dinamik alanlar: Bağlam sağlayan diğer anahtarlar. Örneğin, geçersiz alanın adı (FIELD_LOCATION) veya hataya neden olan değer (FIELD_VALUE).

Örnek hata yanıtları

Aşağıdaki JSON, kaynak adının hatalı biçimlendirildiği bir Merchant API hatasının yapısını göstermektedir.

{
  "error": {
    "code": 400,
    "message": "[name] The part `account` of the resource name in field `name` must be a number, but has value: `abcd`.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "VARIABLE_NAME": "account",
          "FIELD_LOCATION": "name",
          "FIELD_VALUE": "abcd",
          "REASON": "INVALID_NAME_PART_NOT_NUMBER"
        }
      }
    ]
  }
}

Aşağıda, kimlik doğrulama hatası örneği verilmiştir:

{
  "error": {
    "code": 401,
    "message": "The caller does not have access to the accounts: [1234567]",
    "status": "UNAUTHENTICATED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "unauthorized",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_IDS": "[1234567]",
          "REASON": "PERMISSION_DENIED_ACCOUNTS"
        }
      }
    ]
  }
}

Hata alanlarının kararlılığı

Hata işleme mantığı yazarken hangi alanların güvenilir olduğunu ve hangilerinin değişebileceğini bilmek önemlidir.

  • Kararlı alanlar:

  • details.metadata.REASON: Belirli hata tanımlayıcısı. Uygulamanızın kontrol akışı mantığı için bu alandan yararlanmanız gerekir.

    • details.metadata anahtarları: Meta veri eşlemesindeki anahtarlar (ör. FIELD_LOCATION, ACCOUNT_IDS) sabittir.
    • code: Üst düzey HTTP durum kodu (ör. 400, 401, 503) kararlıdır.

  • Kararsız alanlar:

    • message: İnsan tarafından okunabilen hata mesajı kararlı değildir. Yalnızca geliştiricilerin hata ayıklama işlemleri için tasarlanmıştır. message alanının metin içeriğini ayrıştıran veya bu içeriğe dayalı kod yazmayın. Bu içerik, netliği artırmak veya bağlam eklemek için önceden haber verilmeksizin değiştirilebilir.
    • details.metadata değerleri: Anahtarlar sabit olsa da bilgilendirme anahtarlarının değerleri değişebilir. Örneğin, bir HELP_CENTER_LINK anahtarı sağlanırsa işaret ettiği URL, önceden bildirimde bulunulmadan daha yeni bir doküman sayfasına güncellenebilir. Ancak daha önce de belirtildiği gibi details.metadata.REASON değeri sabittir.

En iyi uygulamalar

Entegrasyonunuzun hataları sorunsuz bir şekilde işlemesini sağlamak için aşağıdaki en iyi uygulamaları izleyin.

Mantık için details.metadata.REASON kullanın

Bir hatanın nedenini belirlemek için her zaman metadata haritasındaki belirli REASON değerini kullanın. Birden fazla hata aynı durum kodunu paylaşabileceğinden yalnızca HTTP durum koduna güvenmeyin.

Hata mesajını ayrıştırmayın.

Kararlılık bölümünde belirtildiği gibi, message alanı insanlar tarafından kullanılmak üzere tasarlanmıştır. Dinamik bilgilere (ör. hangi alanın geçersiz olduğu) ihtiyacınız varsa FIELD_LOCATION, VARIABLE_NAME gibi kararlı anahtarları kullanarak bu bilgileri metadata haritasından ayıklayın.

Eksponansiyel geri yüklemeyi uygulama

Geçici olarak kullanılamama veya sıklık sınırlaması olduğunu belirten hatalar için eksponansiyel geri yükleme stratejisi uygulayın. Yani yeniden denemeden önce kısa bir süre bekler ve her başarısız denemeden sonra bekleme süresini artırır.

  • quota/request_rate_too_high: Bu hata, belirli bir kota grubu için dakika kotanızı aştığınızı gösterir. İstek oranınızı azaltın.
  • internal_error: Bunlar genellikle geçicidir. Eksponansiyel geri yüklemeyle yeniden deneme yapılıyor.

Merchant API Destek Ekibi ile iletişime geçme

Belirli bir hata hakkında Merchant API Destek Ekibi ile iletişime geçmeniz gerekiyorsa isteğinizde aşağıdaki bilgileri sağlayın:

  1. Alınan hata yanıtının tam metni
  2. API yönteminin adı
  3. İstek yükü
  4. Yöntemin çağrıldığı ve hataların alındığı zaman damgaları veya zaman aralığı
Önceki
Track usage metrics
Sonraki
Error messages