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ış

Bir 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. Bu standart, uygulamanızın belirli hata senaryolarını programlı 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. En önemlisi, details dizisini de içerir. Hataları programatik olarak işlemek için details içinde bir nesne aramanız gerekir. Burada @type, type.googleapis.com/google.rpc.ErrorInfo'dir.

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

  • domain: Hatanın mantıksal gruplandırmasıdır. Genellikle merchantapi.googleapis.com olur.
  • metadata: Hatayla ilgili dinamik değerlerin haritası. Bu kapsamda:
    • REASON: Hataya özgü, sabit bir tanımlayıcı (ör. INVALID_NAME_PART_NOT_NUMBER, PERMISSION_DENIED_ACCOUNTS). Bu alan her zaman bulunur. 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 hatalarda bulunmaz ancak daha fazla bağlamın gerekebileceği hatalarda kapsamını zaman içinde genişletmeyi planlıyoruz.
    • Diğer dinamik alanlar: Bağlam sağlayan diğer anahtarlar (ör. 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österir.

{
  "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üvenli olduğunu ve hangilerinin değişebileceğini bilmek önemlidir.

  • Sabit alanlar:

  • details.metadata.REASON: Belirli hata tanımlayıcısı. Uygulamanızın kontrol akışı mantığı için bu alana güvenmelisiniz.

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

  • Kararsız alanlar:

    • message: İnsan tarafından okunabilir hata mesajı kararlı değildir. Yalnızca geliştiricilerin hata ayıklaması için tasarlanmıştır. Netliği artırmak veya bağlam eklemek için önceden haber verilmeksizin değişebileceğinden, message alanının metin içeriğini ayrıştıran veya bu içeriğe dayanan kod yazmayın.
    • details.metadata değerleri: Anahtarlar sabit olsa da bilgi anahtarlarının değerleri değişebilir. Örneğin, bir HELP_CENTER_LINK anahtarı sağlanırsa bu anahtarın işaret ettiği URL, önceden bildirimde bulunulmadan daha yeni bir doküman sayfasına güncellenebilir. Ancak daha önce 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 uygulamalardan yararlanın.

Mantık için details.metadata.REASON kullanma

Bir hatanın nedenini belirlemek için her zaman metadata haritasının içindeki REASON öğesini 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. Hangi alanın geçersiz olduğu gibi dinamik bilgilere ihtiyacınız varsa FIELD_LOCATION ve VARIABLE_NAME gibi sabit anahtarları kullanarak bu bilgileri metadata haritasından çıkarın.

Eksponansiyel geri yükleme uygulama

Geçici olarak kullanılamama veya sıklık sınırlaması olduğunu belirten hatalar için üstel geri çekilme stratejisi uygulayın. Bu, yeniden denemeden önce kısa bir süre beklemek ve sonraki her başarısızlıkta bekleme süresini artırmak anlamına gelir.

  • quota/request_rate_too_high: Bu hata, belirli bir kota grubu için dakika kotanızı aştığınızı gösterir. İstek sıklığınızı azaltın.
  • internal_error: Bunlar genellikle geçicidir. Eksponansiyel geri yüklemeyle yeniden deneyin. Not: internal_error, geri çekilme ile birden çok kez yeniden denendikten sonra devam ederse Merchant API desteğiyle nasıl iletişime geçilir? başlıklı makaleye bakın.

Merchant API destek ekibiyle iletişime geçme

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

  1. Alınan tam hata yanıtı
  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ığı