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 Array messages in der Antwort empfohlen. Diese Beispiele finden Sie unten in der Tabelle im Abschnitt Beispiele für Fehlercodes. 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 standardmäßige HTTP-Statuscodes (z.B. 4xx für Clientfehler, 5xx für Serverfehler) für Probleme wie fehlerhafte Anfragen, Authentifizierungsfehler oder Serververfügbarkeit.
  • 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 Downstream-Zahlungsgateway einen 4xx- oder 5xx-Fehler zurückgibt.
  • Beschreiben Sie das Problem im Array messages 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 unbekannten Codes wie "invalid".
    • content: Eine menschenlesbare Beschreibung.
    • severity: Erforderlich, wenn type "error" ist. Dieses Feld gibt explizit an, ob der Fehler schwerwiegend ist (unrecoverable) oder ob Sie den Käufer auffordern können, das Problem zu beheben (recoverable). Sie müssen sich also nicht auf den Fehlercode selbst verlassen.

Nachrichtentypen: Fehler und Warnungen

Das Feld type im Nachrichtenarray gibt den Schweregrad des Problems an. UCP definiert zwei primäre Typen:

• 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 message-error.
  • Die Art eines Fehlers wird durch das Feld severity (unrecoverable oder recoverable) bestimmt, nicht durch den Fehler code.
• warning: Gibt an, dass der Vorgang nicht blockiert wurde, aber es etwas Bemerkenswertes gibt, das dem Nutzer mitgeteilt werden sollte. Dadurch wird der Prozess nicht unterbrochen, aber wichtiger Kontext bereitgestellt. Spezifikation für message-warning

Fehlercode-Referenz

Beispiele für Fehlercodes

Dieser Abschnitt enthält JSON-Beispiele für das messages-Array für bestimmte Fehlercodes.

out_of_stock

Direktkauf eines einzelnen Artikels:

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

Zahlung für mehrere Artikel:

Verwenden Sie das Feld path, um den Index des jeweiligen 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 Bestellebene (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. aufgrund von Verboten in bestimmten Bundesstaaten).

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

Adresse für die Auftragsausführung:

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