Kody błędów

Na tej stronie znajdziesz listę kanonicznych kodów błędów, które musisz zwracać w odpowiedziach 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 reagować na różne scenariusze.

Gdy wystąpi błąd związany z firmą, interfejs API powinien zwrócić komunikat z odpowiednim kodem 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 te 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 czy 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/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: znormalizowany kod z tego przewodnika. Nie używaj ogólnych ani nierozpoznanych kodów, takich jak "invalid".
    • content: Opis zrozumiały dla człowieka.
    • severity: wymagany, gdy type ma wartość "error". To pole wyraźnie wskazuje, czy błąd jest nieodwracalny (unrecoverable), czy pozwala poprosić kupującego o jego naprawienie (recoverable), zamiast polegać na samym kodzie błędu.

Rodzaje komunikatów: błąd a ostrzeżenie

Pole type w tablicy komunikatów wskazuje wagę problemu. UCP określa 2 główne typy:

• error: oznacza, że nie udało się ukończyć żądanej operacji. Platforma lub użytkownik prawdopodobnie będą musieli podjąć działania i spróbować ponownie. Zobacz specyfikację message-error.
  • O tym, czy błąd jest ostateczny, decyduje pole severity (unrecoverable lub recoverable), a nie błąd code.
• warning: oznacza, że operacja nie została zablokowana, ale jest coś, o czym warto poinformować użytkownika. Nie wstrzymuje to procesu, ale dostarcza ważnych informacji. Zobacz specyfikację message-warning.

Odniesienie do kodu błędu

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

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

out_of_stock

Płatność za 1 produkt:

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

Płatność za wiele produktów:

Użyj pola path, aby podać indeks konkretnego produktu, którego nie ma w magazynie.

{
  "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. ze względu na 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 dla płatności:

{
  "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 przypadku interfejsu REST API ten błąd powinien być zwracany 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 przypadku interfejsu REST API ten błąd powinien być zwracany 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."
}