Obsługa odpowiedzi na błędy

Z tego przewodnika dowiesz się, jak obsługiwać błędy zwracane przez Merchant API. Zrozumienie struktury i stabilności odpowiedzi o błędach jest kluczowe do tworzenia niezawodnych integracji, które mogą automatycznie odzyskiwać dane po awariach lub przekazywać użytkownikom przydatne informacje.

Przegląd

Gdy żądanie Merchant API nie powiedzie się, interfejs API zwraca standardowy kod stanu HTTP (4xx lub 5xx) oraz treść odpowiedzi w formacie JSON zawierającą szczegóły błędu. Interfejs Merchant API jest zgodny ze standardem AIP-193 w zakresie szczegółów błędów. Zawiera informacje w formacie czytelnym dla maszyn, które umożliwiają aplikacji zautomatyzowane 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. Zawiera też tablicę details. Aby programowo obsługiwać błędy, poszukaj obiektu w details, w którym @type ma wartość 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 związanych z błędem. Obejmuje ona m.in:
    • REASON: konkretny, stabilny identyfikator dokładnego 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 dodatkowe informacje i instrukcje dotyczące rozwiązania problemu. To pole nie występuje 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, np. nazwa nieprawidłowego pola (FIELD_LOCATION) lub wartość, która spowodowała błąd (FIELD_VALUE).

Przykładowe odpowiedzi na błędy

Poniższy kod JSON pokazuje 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 polegać, a które mogą się zmienić.

  • Pola stałe:

  • details.metadata.REASON: identyfikator konkretnego błędu. W logice przepływu sterowania aplikacji należy polegać na tym polu.

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

  • Niestabilne pola:

    • message: komunikat o błędzie w formie czytelnej dla człowieka nie jest stabilny. Jest on przeznaczony tylko do debugowania przez deweloperów. Nie pisz kodu, który analizuje lub opiera się na treści tekstowej pola message, ponieważ może ona ulec zmianie bez powiadomienia, aby zwiększyć przejrzystość lub dodać kontekst.
    • details.metadata wartości: klucze są stabilne, ale wartości kluczy informacyjnych mogą się zmieniać. Jeśli na przykład podasz HELP_CENTER_LINKklucz, konkretny adres URL, na który on wskazuje, może zostać zaktualizowany do nowszej strony dokumentacji bez wcześniejszego powiadomienia. Jak wspomnieliśmy wcześniej, wartość details.metadata.REASON jest jednak stabilna.

Sprawdzone metody

Aby mieć pewność, że integracja prawidłowo obsługuje błędy, postępuj zgodnie z tymi sprawdzonymi metodami.

Użyj details.metadata.REASON do logiki

Zawsze używaj konkretnego REASON w metadata mapie, aby określić przyczynę błędu. Nie polegaj tylko na kodzie stanu HTTP, ponieważ wiele błędów może mieć ten sam kod stanu.

Nie analizuj komunikatu o błędzie

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

Wdrażanie wzrastającego czasu do ponowienia

W przypadku błędów wskazujących na tymczasową niedostępność lub ograniczenie liczby żądań wdróż strategię wzrastającego czasu do ponowienia. Oznacza to, że przed ponowną próbą należy odczekać krótki czas, a z każdą kolejną nieudaną próbą wydłużać czas oczekiwania.

  • quota/request_rate_too_high: ten błąd oznacza, że został przekroczony limit minut w określonej grupie limitów. Zmniejsz częstotliwość wysyłania żądań.
  • internal_error: zazwyczaj są one przejściowe. Ponów próbę ze wzrastającym czasem do ponowienia.

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

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

  1. dokładny komunikat o błędzie,
  2. Nazwa metody interfejsu API
  3. ładunek żądania,
  4. Sygnatury czasowe lub zakres czasu, w którym wywołano metodę i odebrano błędy.
Wstecz
Track usage metrics
Dalej
Error messages