Kody błędów

Ta strona zawiera listę kanonicznych kodów błędów, które musisz zwracać w odpowiedziach interfejsu API podczas integracji z Google za pomocą protokołu Universal Commerce Protocol (UCP). Spójne kody błędów zapewniają jasną komunikację i pomagają Google odpowiednio obsługiwać różne scenariusze.

Gdy wystąpi błąd biznesowy, interfejs API powinien zwrócić komunikat z odpowiednim code z tabeli. W przypadku niektórych kodów błędów zalecana jest określona struktura JSON dla tablicy messages w odpowiedzi. Przykłady znajdziesz w sekcji Przykłady kodów błędów poniżej tabeli. W tych przykładach użyj pola path, aby podać bardziej szczegółowe informacje o lokalizacji błędu w obiekcie żądania lub odpowiedzi.

Obsługa błędów

Sposób zgłaszania błędów zależy od ich typu:

  • Błędy protokołu lub serwera:

    • W przypadku problemów takich jak nieprawidłowo sformułowane żądania, błędy uwierzytelniania lub niedostępność serwera używaj standardowych kodów stanu HTTP (np. 4xx w przypadku błędów klienta, 5xx w przypadku błędów serwera).
    • Szczegółowe informacje znajdziesz w specyfikacji UCP.

  • Błędy lub ostrzeżenia dotyczące logiki biznesowej:

    • Zwróć stan HTTP 200 OK. Obejmuje to odrzucenie płatności i odrzucenie z powodu oszustwa, nawet jeśli podrzędna bramka płatności zwraca błąd 4xx lub 5xx.
    • Opisz problem w tablicy messages w treści odpowiedzi JSON.
    • Każdy obiekt w tablicy messages musi zawierać:
      • type: "error" lub "warning"
      • code: standardowy kod z tego przewodnika. Nie używaj ogólnych ani nierozpoznanych kodów, takich jak "invalid".
      • content: opis zrozumiały dla człowieka.
      • severity: wymagane, gdy type to "error". To pole wyraźnie wskazuje, czy błąd jest krytyczny (unrecoverable), czy też pozwala poprosić kupującego o jego naprawienie (recoverable), zamiast polegać na samym kodzie błędu.

Typy wiadomości: błąd a ostrzeżenie

Pole type w tablicy wiadomości wskazuje ważność problemu. UCP definiuje 2 główne typy:

  • error: wskazuje, że nie udało się ukończyć żądanej operacji. Platforma lub użytkownik prawdopodobnie będą musieli podjąć działania i spróbować ponownie. Więcej informacji znajdziesz w specyfikacji message-error specification.
    • O tym, czy błąd jest krytyczny, decyduje pole severity (unrecoverable lub recoverable), a nie code błędu.
  • warning: wskazuje, że operacja nie została zablokowana, ale jest coś ważnego, co należy przekazać użytkownikowi. Nie powoduje to przerwania procesu, ale zapewnia ważny kontekst. Więcej informacji znajdziesz w specyfikacji message-warning specification.

Odniesienie do kodu błędu

Kod błędu Zalecany typ Opis
out_of_stock Błąd Produkt jest niedostępny. Zwykle powoduje to ucp.status: “error”. Użyj pola path, aby wskazać indeks produktu w procesie płatności za wiele produktów. Zobacz przykład poniżej.
item_unavailable Błąd Nie udało się znaleźć produktu. W przypadku tych błędów związanych z produktem zwykle powoduje to ucp.status: “error”.
item_ineligible Błąd Produkt istnieje, ale nie można go kupić za pomocą UCP.
quantity_invalid_limit_exceeded Błąd Żądana ilość przekracza dopuszczalny limit. Zobacz przykład poniżej.
quantity_invalid_minimum_not_met Błąd Żądana ilość jest mniejsza od minimalnej wymaganej.
totals_changed Ostrzeżenie Cena lub inne sumy uległy zmianie od ostatniego kroku. Użyj pola path, aby wskazać, która suma uległa zmianie. Zobacz przykład poniżej.
totals_invalid_minimum_not_met Błąd Wartość zamówienia nie spełnia minimalnego wymogu.
missing_buyer_info Błąd Brakuje wymaganych informacji o kupującym. Użyj pola path, aby określić brakujące pole. Zobacz przykład poniżej.
address_undeliverable Błąd Jest to standardowy kod błędu UCP. Użyj pola path, aby wskazać konkretne miejsce docelowe lub produkt objęty ograniczeniami. Zobacz przykład poniżej.
address_unverifiable Błąd Nie udało się zweryfikować podanego adresu. Użyj pola path, aby wskazać, czy jest to adres realizacji czy adres rozliczeniowy. Zobacz przykład poniżej.
missing_fulfillment_info Błąd Brakuje wymaganych informacji o realizacji. Użyj pola path, aby określić brakujące pole.
eligibility_invalid Błąd Użytkownik lub zamówienie nie kwalifikuje się do wykonania tej czynności. Jest to standardowy kod błędu UCP. Użyj pola path, aby podać szczegóły.
discount_code_invalid Ostrzeżenie Kod rabatowy jest nieprawidłowy. Nie znaleziono kodu lub jest on nieprawidłowy.
discount_code_expired Ostrzeżenie Kod rabatowy stracił ważność.
discount_code_already_applied Ostrzeżenie Kod rabatowy został już zastosowany.
discount_code_combination_disallowed Ostrzeżenie Kodu rabatowego nie można łączyć z innymi ofertami.
discount_code_user_not_logged_in Ostrzeżenie Aby użyć kodu rabatowego, użytkownik musi być zalogowany.
discount_code_user_ineligible Ostrzeżenie Użytkownik nie może użyć kodu rabatowego.
missing_billing_info Błąd Brakuje wymaganych informacji rozliczeniowych. Użyj pola path, aby określić brakujące pola adresu rozliczeniowego. Zobacz przykład poniżej.
identity_required Błąd Do wykonania żądanej operacji wymagana jest tożsamość użytkownika, ale nie została ona podana lub jest nieprawidłowa, nieważna lub nie można jej zweryfikować. W przypadku REST użyj kodu stanu 401. Zobacz przykład poniżej.
insufficient_scope Błąd Token tożsamości użytkownika jest prawidłowy, ale nie zawiera zakresów wymaganych przez operację. W przypadku REST użyj kodu stanu 403. Zobacz przykład poniżej.
payment_declined Błąd Płatność została odrzucona przez wydawcę karty lub bank. Przyczyny mogą obejmować niewystarczające środki, podejrzenie oszustwa lub problemy z kartą. Zobacz przykład poniżej.
payment_failed Błąd Płatność nie powiodła się z powodu problemu technicznego podczas przetwarzania, takiego jak błąd sieci, przekroczenie limitu czasu bramy lub problem z integracją, który uniemożliwił bankowi podjęcie decyzji.
payment_ineligible Błąd Wybrana forma płatności nie jest akceptowana. Odpowiednie w przypadkach, gdy użytkownik musi spróbować użyć innej formy płatności.
rejected_for_fraud Błąd Zamówienie zostało odrzucone z powodu podejrzenia oszustwa. Zobacz przykład poniżej.

Przykłady kodów błędów

Ta sekcja zawiera przykłady JSON dla tablicy messages w przypadku określonych kodów błędów.

out_of_stock

Proces płatności za 1 produkt:

{
  "type": "error",
  "severity": "unrecoverable",
  "code": "out_of_stock",
  "content": "Unfortunately, the item 'Example Product 1' is out of stock."
}

Proces płatności za wiele produktów:

Użyj pola path, aby wskazać indeks konkretnego produktu, który jest niedostępny.

{
  "type": "error",
  "severity": "recoverable",
  "code": "out_of_stock",
  "path": "$.checkout.line_items[1]",
  "content": "The item 'Example Product 2' is out of stock. Remove it from your cart to continue."
}

quantity_invalid_limit_exceeded

{
  "type": "error",
  "severity": "recoverable",
  "code": "quantity_invalid_limit_exceeded",
  "path": "$.checkout.line_items[0].quantity",
  "content": "The requested quantity for 'Example Product 2' exceeds the maximum allowed limit of 5."
}

totals_changed

{
  "type": "warning",
  "code": "totals_changed",
  "path": "$.totals[2]",
  "content": "Shipping cost has changed."
}

missing_buyer_info

{
  "type": "error",
  "severity": "recoverable",
  "code": "missing_buyer_info",
  "path": "$.buyer.first_name",
  "content": "Missing buyer first name."
}

address_undeliverable

Ograniczenie na poziomie zamówienia (np. kod pocztowy nie jest obsługiwany):

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_undeliverable",
  "content": "Delivery is not supported for the provided zipcode."
}

Ograniczenie na poziomie produktu:

Użyj pola path, aby wskazać konkretny produkt, którego nie można dostarczyć do wybranego miejsca docelowego (np. zakazy obowiązujące w danym stanie).

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_undeliverable",
  "path": "$.checkout.line_items[1]",
  "content": "The item 'Example Product 2' cannot be delivered to the selected address."
}

address_unverifiable

Adres rozliczeniowy:

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_unverifiable",
  "path": "$.payment.instruments[0].billing_address",
  "content": "Invalid billing address. Update the address before trying again."
}

Adres realizacji:

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_unverifiable",
  "path": "$.fulfillment.methods[0].destinations[0]",
  "content": "The fulfillment address couldn't be verified. Update the address and try again."
}

missing_billing_info

Użyj pola path, aby określić brakujące pola w adresie rozliczeniowym.

{
  "type": "error",
  "severity": "recoverable",
  "code": "missing_billing_info",
  "path": "$.payment.instruments[0].billing_address.street_address",
  "content": "Missing billing street address."
}

identity_required

W interfejsie REST API ten błąd należy zwracać z kodem stanu HTTP 401.

{
  "type": "error",
  "severity": "requires_buyer_review",
  "code": "identity_required",
  "content": "User identity is required to access order history."
}

insufficient_scope

W interfejsie REST API ten błąd należy zwracać z kodem stanu HTTP 403.

{
  "type": "error",
  "severity": "requires_buyer_review",
  "code": "insufficient_scope",
  "content": "This operation requires scopes: dev.ucp.shopping.order:read, dev.ucp.shopping.order:manage"
}

Błędy płatności

payment_declined

{
  "type": "error",
  "severity": "recoverable",
  "code": "payment_declined",
  "path": "$.payment.instruments[0]",
  "content": "Payment was declined by the issuer. Try a different payment method or contact your bank."
}

rejected_for_fraud

{
  "type": "error",
  "severity": "recoverable",
  "code": "rejected_for_fraud",
  "path": "$.payment.instruments[0]",
  "content": "The order was rejected due to suspected fraud. Try a different payment method."
}