Obsługa odpowiedzi na błędy

Z tego przewodnika dowiesz się, jak postępować z błędami zwracanymi przez interfejs Merchant API. Zrozumienie struktury i stabilności odpowiedzi o błędzie jest kluczowe dla tworzenia solidnych integracji, które mogą automatycznie odzyskiwać dane po awariach lub dostarczać użytkownikom przydatne informacje zwrotne.

Przegląd

Gdy żądanie do interfejsu Merchant API nie powiedzie się, interfejs API zwraca standardowy kod stanu HTTP (4xx lub 5xx) i treść odpowiedzi JSON zawierającą szczegółowe informacje o błędzie. Interfejs Merchant API jest zgodny ze standardem AIP-193 dotyczącym szczegółów błędów. Udostępnia on informacje w formacie czytelnym dla komputerów, co pozwala aplikacji na automatyczne obsługiwanie konkretnych scenariuszy błędów.

Struktura odpowiedzi na błąd

Odpowiedź o błędzie to obiekt JSON zawierający standardowe pola, takie jak code, message i status. Co ważne, zawiera też tablicę details. Aby obsłużyć błędy automatycznie, poszukaj obiektu w details, gdzie @type to type.googleapis.com/google.rpc.ErrorInfo.

Ten obiekt ErrorInfo zawiera stabilne, uporządkowane dane o błędzie:

  • domain: logiczne grupowanie błędu, zwykle merchantapi.googleapis.com.
  • metadata: mapa wartości dynamicznych powiązanych z błędem. Obejmuje ona m.in:
    • REASON: konkretny, stały identyfikator błędu (np. INVALID_NAME_PART_NOT_NUMBER, PERMISSION_DENIED_ACCOUNTS). To pole jest zawsze obecne. Użyj tego pola do szczegółowej obsługi błędów w logice aplikacji.
    • HELP_CENTER_LINK: zawiera dodatkowy kontekst i instrukcje dotyczące rozwiązania problemu. To pole nie jest dostępne w przypadku wszystkich błędów, ale planujemy z czasem rozszerzyć jego zakres na błędy, w przypadku których może być potrzebny szerszy kontekst.
    • Inne pola dynamiczne: inne klucze dostarczające kontekst, takie jak nazwa nieprawidłowego pola (FIELD_LOCATION) lub wartość, która spowodowała błąd (FIELD_VALUE).

Przykładowe odpowiedzi z błędem

Poniższy kod JSON przedstawia strukturę błędu interfejsu Merchant API, w którym nazwa zasobu jest nieprawidłowa.

{
  "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"
        }
      }
    ]
  }
}

Oto przykład błędu uwierzytelniania:

{
  "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"
        }
      }
    ]
  }
}

Stabilność pól błędów

Podczas pisania logiki obsługi błędów ważne jest, aby wiedzieć, na których polach można bezpiecznie polegać, a które mogą się zmienić.

  • Pola stabilne:

  • details.metadata.REASON: identyfikator konkretnego błędu. To pole powinno być używane w logice przepływu sterowania aplikacji.

    • Klucze details.metadata: klucze w mapie metadanych (np. FIELD_LOCATION, ACCOUNT_IDS) są stabilne.
    • code: kod stanu HTTP wysokiego poziomu (np. 400, 401, 503) jest stabilny.

  • Pola niestabilne:

    • message: komunikat o błędzie zrozumiały dla człowieka nie jest stabilny. Służy tylko do debugowania przez dewelopera. Nie pisz kodu, który analizuje zawartość tekstową pola message lub na niej polega, ponieważ może ona ulec zmianie bez powiadomienia w celu zwiększenia przejrzystości lub dodania kontekstu.
    • Wartości details.metadata: o ile klucze są stałe, o tyle wartości kluczy informacyjnych mogą się zmieniać. Jeśli na przykład podany jest klucz HELP_CENTER_LINK, konkretny adres URL, na który wskazuje, może zostać zaktualizowany do nowszej strony dokumentacji bez wcześniejszego powiadomienia. Jednak, jak wspomnieliśmy wcześniej, wartość details.metadata.REASON jest stabilna.

Sprawdzone metody

Postępuj zgodnie z tymi sprawdzonymi metodami, aby integracja prawidłowo obsługiwała błędy.

Używanie details.metadata.REASON do logiki

Aby określić przyczynę błędu, zawsze używaj konkretnego elementu REASON w mapie metadata. Nie polegaj wyłącznie na kodzie stanu HTTP, ponieważ wiele błędów może mieć ten sam kod stanu.

Nie analizuj komunikatu o błędzie.

Jak wspomniano w sekcji dotyczącej stabilności, pole message jest przeznaczone dla ludzi. Jeśli potrzebujesz informacji dynamicznych (np. o tym, które pole było nieprawidłowe), wyodrębnij je z mapy metadata, używając stabilnych kluczy, takich jak FIELD_LOCATION, VARIABLE_NAME.

Wdrażanie wzrastającego czasu do ponowienia

W przypadku błędów wskazujących na tymczasową niedostępność lub ograniczenie liczby żądań zastosuj strategię wzrastającego czasu do ponowienia. Oznacza to, że przed ponowną próbą należy odczekać chwilę, a po każdym kolejnym niepowodzeniu wydłużać czas oczekiwania.

  • quota/request_rate_too_high: ten błąd oznacza, że przekroczono limit minutowy dla określonej grupy limitów. Zmniejsz częstotliwość wysyłania żądań.
  • internal_error: te błędy są zwykle przejściowe. Podejmuje ponowne próby ze wzrastającym czasem do ponowienia.

Jak skontaktować się z zespołem pomocy Merchant API

Jeśli chcesz skontaktować się z zespołem pomocy Merchant API w sprawie konkretnego błędu, podaj w prośbie te informacje:

  1. dokładną treść otrzymanego komunikatu o błędzie,
  2. Nazwa metody interfejsu API
  3. ładunek żądania,
  4. sygnatury czasowe lub zakres czasu, w którym metoda została wywołana i wystąpiły błędy;
Wstecz
Track usage metrics
Dalej
Error messages