Fehlercodes

Auf dieser Seite finden Sie die kanonischen Fehlercodes, die Sie in Ihren API-Antworten zurückgeben müssen, wenn Sie das Universal Commerce Protocol (UCP) für die Integration mit Google verwenden. Einheitliche Fehlercodes sorgen für eine klare Kommunikation und helfen Google, verschiedene Szenarien angemessen zu behandeln.

Wenn ein Geschäftsfehler auftritt, sollte Ihre API eine Antwortnachricht zurückgeben, die den entsprechenden code aus der Tabelle enthält. Für einige Fehlercodes wird eine bestimmte JSON-Struktur für das messages-Array in der Antwort empfohlen. Diese Beispiele finden Sie im Abschnitt Beispiele für Fehlercodes unter der Tabelle. In diesen Beispielen sollten Sie das Feld path verwenden, um genauere Informationen zum Ort des Fehlers im Anfrage- oder Antwortobjekt anzugeben.

Fehlerbehandlung

Wie Sie Fehler melden, hängt vom Fehlertyp ab:

• Protokoll-/Serverfehler :

  • Verwenden Sie Standard-HTTP-Statuscodes (z.B. 4xx für Clientfehler, 5xx für Serverfehler) für Probleme wie fehlerhafte Anfragen, Authentifizierungsfehler oder Serverausfälle.
  • Weitere Informationen finden Sie in der UCP-Spezifikation.

• Fehler/Warnungen in der Geschäftslogik :

  • Geben Sie den Status HTTP 200 OK zurück. Dazu gehören abgelehnte Zahlungen und Betrugsablehnungen, auch wenn Ihr nachgelagertes Zahlungs-Gateway einen 4xx- oder 5xx-Fehler zurückgibt.
  • Beschreiben Sie das Problem im messages-Array im JSON-Antworttext.
  • Jedes Objekt im messages-Array muss Folgendes enthalten:
    • type: "error" oder "warning"
    • code: Ein standardisierter Code aus diesem Leitfaden. Verwenden Sie keine generischen oder nicht erkannten Codes wie "invalid".
    • content: Eine für Menschen lesbare Beschreibung.
    • severity: Erforderlich, wenn type "error" ist. In diesem Feld wird explizit angegeben, ob der Fehler schwerwiegend (unrecoverable) ist, oder Sie können den Käufer auffordern, das Problem zu beheben (recoverable), anstatt sich auf den Fehlercode selbst zu verlassen.

Nachrichtentypen: Fehler und Warnung

Das Feld type im Nachrichten-Array gibt den Schweregrad des Problems an. UCP definiert zwei Haupttypen:

• error: Gibt an, dass der angeforderte Vorgang nicht abgeschlossen werden konnte. Die Plattform oder der Nutzer muss wahrscheinlich Maßnahmen ergreifen und es noch einmal versuchen. Weitere Informationen finden Sie in der Spezifikation für Nachrichtenfehler.
  • Die Schwere eines Fehlers wird durch das severity Feld (unrecoverable oder recoverable) bestimmt, nicht durch den Fehler code.
• warning: Gibt an, dass der Vorgang nicht blockiert wurde, aber es gibt etwas Wichtiges, das dem Nutzer mitgeteilt werden sollte. Dadurch wird der Prozess nicht angehalten, aber wichtiger Kontext bereitgestellt. Weitere Informationen finden Sie in der Spezifikation für Nachrichtenwarnungen.

Fehlercode-Referenz

Beispiele für Fehlercodes

In diesem Abschnitt finden Sie JSON-Beispiele für das messages-Array für bestimmte Fehlercodes.

out_of_stock

Checkout mit einem Artikel:

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

Checkout mit mehreren Artikeln:

Verwenden Sie das Feld path, um den Index des Artikels anzugeben, der nicht auf Lager ist.

{
  "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

Einschränkung auf Bestellungsebene (z.B. Postleitzahl nicht unterstützt):

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

Einschränkung auf Artikelebene:

Verwenden Sie das Feld path, um einen bestimmten Artikel anzugeben, der nicht an das ausgewählte Ziel geliefert werden kann (z.B. staatsspezifische Verbote).

{
  "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

Rechnungsadresse:

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

Lieferadresse:

{
  "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

Verwenden Sie das Feld path, um fehlende Felder in der Rechnungsadresse anzugeben.

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

identity_required

In der REST API sollte dieser Fehler mit dem HTTP-Statuscode 401 zurückgegeben werden.

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

insufficient_scope

In der REST API sollte dieser Fehler mit dem HTTP-Statuscode 403 zurückgegeben werden.

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

Fehler beim Zahlungsvorgang

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."
}