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 się nie powiedzie, interfejs API zwraca standardowy kod stanu HTTP (4xx lub 5xx) oraz treść odpowiedzi JSON zawierającą szczegółowe informacje o błędzie. Merchant API jest zgodny ze standardem AIP-193 dotyczącym szczegółów błędów, dzięki czemu udostępnia informacje w formacie odczytywalnym przez maszyny, co pozwala aplikacji programowo obsługiwać określone scenariusze 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 klucze zawierają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 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 czytelny 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 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, do którego prowadzi, 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 integracja prawidłowo obsługiwała błędy, 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 został przekroczony limit minutowy dla określonej grupy limitów. Zmniejsz częstotliwość wysyłania żądań.
• internal_error: są to zwykle błędy 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 z wydłużonym 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 się skontaktować 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.