Obsługa odpowiedzi na błędy

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

Przegląd

Gdy żądanie Merchant API zakończy się niepowodzeniem, 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 dotyczącym szczegółów błędów. Zawiera informacje czytelne dla maszyn, które umożliwiają aplikacji programowe 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ługiwać błędy programowo, 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 powiązanych z błędem. Obejmuje to:
    • REASON: konkretny, stały identyfikator dokładnego błędu (np. INVALID_NAME_PART_NOT_NUMBER, PERMISSION_DENIED_ACCOUNTS). To pole jest zawsze obecne. Użyj tego pola, aby w logice aplikacji precyzyjnie obsługiwać błędy.
    • HELP_CENTER_LINK: zawiera dodatkowy kontekst 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 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 polegać, a które mogą się zmienić.

  • Stałe pola:

  • 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 stabilna.

  • 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: chociaż klucze są stałe, wartości kluczy informacyjnych mogą się zmieniać. Jeśli na przykład podasz klucz HELP_CENTER_LINK, 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

Aby określić przyczynę błędu, zawsze używaj konkretnego elementu REASON w mapie metadata. 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 szybkości wdrażaj strategię wykładniczego wycofywania. 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: zwykle są one przejściowe. Ponów próbę ze wzrastającym czasem do ponowienia. Uwaga: jeśli błąd internal_error nadal występuje po kilku próbach z wycofywaniem, zapoznaj się z artykułem Jak skontaktować się z zespołem pomocy Merchant API.

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ładna odpowiedź 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;