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 jest kluczowe do tworzenia solidnych 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) i treść odpowiedzi w formacie JSON zawierającą szczegóły błędu. Merchant API jest zgodny ze standardem AIP-193 dotyczącym szczegółów błędu, dostarczając 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 ona 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 powiązanych z błędem. Obejmuje ona m.in:
    • 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 do szczegółowej obsługi błędów w logice aplikacji.
    • HELP_CENTER_LINK: zawiera dodatkowe informacje i instrukcje, które pomogą rozwiązać problem. 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 o błędach

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: konkretny identyfikator błędu. Powinien on być używany w logice przepływu sterowania aplikacji.

    • details.metadata klucze: klucze w mapie metadanych (np. FIELD_LOCATION, ACCOUNT_IDS) są stałe.
    • 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 zawartości tekstowej pola message, ponieważ może się ona zmienić bez powiadomienia, aby poprawić 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

Zawsze używaj konkretnego kodu REASON w mapie metadata, 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 użytkowników. 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: te problemy są zwykle przejściowe. Ponów próbę ze wzrastającym czasem do ponowienia.

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

Jeśli chcesz skontaktować się z zespołem pomocy ds. interfejsu 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;
Wstecz
Track usage metrics
Dalej
Error messages