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 na błędy jest kluczowe do tworzenia niezawodnych integracji, które mogą automatycznie odzyskiwać sprawność po awariach lub przekazywać użytkownikom przydatne informacje.

Przegląd

Gdy żądanie do interfejsu Merchant API nie powiedzie się, interfejs API zwraca standardowy kod stanu HTTP (4xx lub 5xx) oraz treść odpowiedzi JSON zawierającą szczegóły błędu. Merchant API jest zgodny ze standardem AIP-193 dotyczącym szczegółów błędów, udostępniając informacje w formacie odczytywalnym przez maszyny, co umożliwia aplikacji programowe obsługiwanie określonych scenariuszy błędów.

Struktura odpowiedzi na błędy

Odpowiedź na błąd to obiekt JSON, który zawiera standardowe pola, takie jak code, message, i status. Co najważniejsze, zawiera też tablicę details. Aby programowo obsługiwać błędy, poszukaj w tablicy details obiektu, w którym @type ma wartość type.googleapis.com/google.rpc.ErrorInfo.

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

• domena: logiczne grupowanie błędu, zwykle merchantapi.googleapis.com.
• metadata: mapa wartości dynamicznych związanych z błędem. Obejmuje ona:
  • 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 precyzyjnej obsługi błędów w logice aplikacji.
  • 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 których może być potrzebny dodatkowy kontekst.
  • Inne pola dynamiczne: inne pola zawierające kontekst, np. nazwę 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 Merchant API, w którym nazwa zasobu była 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 stabilne:

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

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

• Pola niestabilne:

  • message: komunikat o błędzie w języku naturalnym nie jest stabilny. Jest on przeznaczony tylko do debugowania przez deweloperów. Nie pisz kodu, który analizuje lub opiera się na treści pola message field, ponieważ może się ona zmienić bez powiadomienia, aby zwiększyć przejrzystość lub dodać kontekst.
  • Wartości details.metadata: chociaż klucze są stabilne, 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. Jak wspomnieliśmy wcześniej, wartość details.metadata.REASON jest stabilna.

Sprawdzone metody

Aby zapewnić prawidłową obsługę błędów w integracji, postępuj zgodnie z tymi sprawdzonymi metodami.

Używaj details.metadata.REASON w logice

Aby określić przyczynę błędu, zawsze używaj konkretnego pola 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 do odczytu przez człowieka. 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ń wdroż strategię wzrastającego czasu do ponowienia. Oznacza to, że przed ponowieniem próby należy odczekać krótki czas, a z każdym kolejnym niepowodzeniem czas oczekiwania powinien się wydłużać.

• 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. Ponów próbę ze wzrastającym czasem do ponowienia. Uwaga: jeśli internal_error nadal występuje po kilku próbach ponowienia ze wzrastającym czasem do ponowienia, zapoznaj się z sekcją Jak skontaktować się z zespołem pomocy ds. Merchant API support.

Jak skontaktować się z zespołem pomocy ds. 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ź na błąd
2. Nazwa metody interfejsu API
3. Ładunek żądania
4. Sygnatury czasowe lub zakres czasu, w którym wywołano metodę i odebrano błędy