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 w formacie JSON zawierającą szczegółowe informacje o błędzie. 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 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ć, które pola są bezpieczne i 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 przeznaczony tylko do debugowania przez deweloperów. Nie pisz kodu, który analizuje lub opiera się na treści tekstowej 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 podano 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 mieć pewność, że integracja będzie prawidłowo obsługiwać 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 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 po kilku próbach z wzrastającym czasem do ponowienia nadal występuje błąd internal_error, zapoznaj się z sekcją Jak skontaktować się z zespołem pomocy Merchant API API.

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 zgłoszeniu 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