Fehler #1: Rückgabe eines Teils des Katalogs
Das Problem: Der GET /ucp/v1/catalog-Endpunkt paginiert korrekt, lässt aber Produkte ohne Bilder, nicht vorrätige Artikel oder Produkte in bestimmten Kategorien aus. KI-Agenten erhalten eine unvollständige Ansicht Ihres Inventars.
Die Lösung: Nehmen Sie alle aktiven Produkte auf, einschließlich der vorübergehend nicht vorrätigen (mit availability: "OutOfStock"). Agenten verwenden den Verfügbarkeitsstatus, um Einkäufe zu planen; zu wissen, dass ein Produkt existiert, aber derzeit nicht verfügbar ist, ist nützliche Information. Filtern Sie niemals nach Lagerstatus auf Katalogebene.
Fehler #2: Veraltete Bestandsdaten
Das Problem: Der Katalog-Endpunkt gibt Lagerbestände zurück, die alle 24 Stunden aktualisiert werden, aber Ihr tatsächlicher Bestand ändert sich in Echtzeit. Ein KI-Agent bestätigt den Bestand für einen Kunden, der Kunde genehmigt den Kauf, und der Checkout schlägt fehl, weil der Artikel 6 Stunden zuvor ausverkauft war.
Die Lösung: Implementieren Sie einen dedizierten GET /ucp/v1/products/{id}/availability-Endpunkt, der den Live-Bestand abfragt. Der Checkout-Flow muss die Verfügbarkeit zum Zeitpunkt der Auftragserstellung erneut überprüfen und sich nicht auf den Katalog-Cache verlassen. Webhook-Unterstützung für Bestandsänderungen wird dringend empfohlen.
Fehler #3: Fehlende Pflichtfelder in Produktobjekten
Das Problem: UCP definiert Pflichtfelder für Produktobjekte: id, name, description, price, currency, availability, category. Viele Implementierungen lassen category (unter Verwendung einer proprietären Taxonomie) oder gtin / mpn (nützlich, aber als optional behandelt) weg. Agenten, die nach Kategorie filtern oder GTINs über Händler hinweg abgleichen, werden Ihre Produkte übersehen.
Die Lösung: Ordnen Sie Ihre internen Kategorien der UCP-Standardtaxonomie zu. Fügen Sie GTINs und MPNs für alle Produkte hinzu, bei denen diese existieren, sie ermöglichen es Agenten, identische Produkte über mehrere Händler hinweg zu vergleichen.
Fehler #4: Ablauf des Authentifizierungstokens wird nicht behandelt
Das Problem: AP2-Authentifizierungstoken haben ein Gültigkeitsfenster. Wenn Ihre Implementierung die Token-Aktualisierung nicht handhabt, schlagen agentische Checkout-Sitzungen, die länger als das Gültigkeitsfenster des Tokens dauern, mitten in der Transaktion fehl.
Die Lösung: Implementieren Sie eine Token-Aktualisierungslogik in Ihrem Checkout-Handler. Wenn ein AP2-Token während einer Transaktion kurz vor dem Ablauf steht, fordern Sie eine Aktualisierung an, bevor Sie fortfahren. Protokollieren Sie Token-Ablaufereignisse, um festzustellen, ob dies zu Abbrüchen führt.
Fehler #5: Nichtssagende Produktnamen
Das Problem: Produktnamen wie "Modell XR-2200B" oder "SKU-48291" sind in Ihrem internen System aussagekräftig, aber für einen KI-Agenten, der versucht, eine natürlichsprachliche Anfrage eines Benutzers ("eine Edelstahl-French-Press für 4 Tassen") abzugleichen, unverständlich.
Die Lösung: Produktnamen in UCP-Katalogantworten sollten menschenlesbar und beschreibend sein. "Edelstahl-French-Press, 4 Tassen / 600ml" ist für einen Agenten weitaus nützlicher als ein Modellcode. Erwägen Sie ein separates agent_name-Feld, das für den Abgleich natürlicher Sprache optimiert ist.
Fehler #6: Rückgaberichtlinie nicht maschinenlesbar
Das Problem: Die UCP-Spezifikation enthält ein returnPolicy-Objekt in Checkout-Antworten. Viele Implementierungen geben eine URL zurück, die auf die Seite mit der Rückgaberichtlinie verweist, anstatt strukturierte Daten. KI-Agenten können HTML nicht parsen, um Richtlinienbedingungen zu extrahieren.
Die Lösung: Geben Sie ein strukturiertes returnPolicy-Objekt mit den Feldern zurück: returnWindowDays (Ganzzahl), returnType ("free" / "paid" / "exchange-only"), conditions (Array von einfachsprachigen Zeichenketten). Dies ermöglicht es Agenten, Benutzer vor der Kaufbestätigung genau über die Rückgabebedingungen zu informieren.
Fehler #7: Ratenbegrenzung zu aggressiv eingestellt
Das Problem: Händler legen Ratenbegrenzungen für UCP-Endpunkte fest, um ihre Infrastruktur zu schützen. Limits von 10 Anfragen/Minute mögen für menschliche Browser angemessen erscheinen, sind aber für KI-Agenten unzureichend, die schnelle sequentielle Anfragen stellen können, um Produkte zu vergleichen oder den Bestand über mehrere Kategorien hinweg zu überprüfen.
Die Lösung: Differenzieren Sie Ratenbegrenzungen nach Endpunkttyp. Kataloglesevorgänge können aus dem Cache mit großzügigen Limits (100+ Anfragen/Minute) bedient werden. Checkout-Endpunkte sollten engere Limits (10–30/Minute) haben, da sie eine Bestandsreservierung beinhalten. Implementieren Sie ordnungsgemäße HTTP 429-Antworten mit Retry-After-Headern, damit Agenten anmutig zurücktreten können, anstatt fehlzuschlagen.
Fehler #8: HTTPS-Zertifikatsprobleme auf der UCP-Subdomain
Das Problem: Viele Händler hosten UCP-Endpunkte auf einer Subdomain (z. B. api.yourstore.com) mit einem separat verwalteten SSL-Zertifikat. Abgelaufene Zertifikate, falsch konfigurierte SANs oder fehlende Zwischenzertifikate führen dazu, dass Agenten Ihre Endpunkte als nicht vertrauenswürdig ablehnen.
Die Lösung: Verwenden Sie die automatische Zertifikatserneuerung (Let's Encrypt mit certbot oder die verwalteten Zertifikate Ihres CDN-Anbieters). Richten Sie Überwachungswarnungen für Zertifikate ein, die innerhalb von 30 Tagen ablaufen. Testen Sie Ihre UCP-Subdomain regelmäßig mit SSL Labs.
Fehler #9: Checkout-Bestätigung wird nicht in Echtzeit zurückgegeben
Das Problem: Ihr POST /ucp/v1/checkout-Endpunkt reiht die Bestellung zur Verarbeitung ein und gibt eine 202 Accepted-Antwort zurück, wobei erwartet wird, dass der Agent die Bestätigung abfragt. Viele Agenten interpretieren alles außer einem synchronen 200 OK mit einer Bestell-ID als Fehler.
Die Lösung: Verarbeiten Sie den Checkout synchron und geben Sie innerhalb von 3 Sekunden eine 200-Antwort mit einem vollständigen Bestellobjekt (Bestell-ID, voraussichtliche Lieferung, Bestätigungsnummer) zurück. Wenn Ihr Backend eine asynchrone Verarbeitung erfordert, implementieren Sie einen schnellen synchronen Vorvalidierungsschritt, der eine optimistische Bestell-ID zurückgibt, und aktualisieren Sie dann über Webhook.
Fehler #10: Nicht mit der offiziellen UCP-Testsuite testen
Das Problem: Entwickler testen UCP-Endpunkte mit manuellen Curl-Befehlen oder Postman, nicht mit der offiziellen UCP-Zertifizierungstestsuite. Diese manuellen Tests übersehen Grenzfälle, die die Spezifikation definiert: fehlerhafte Anfragen, teilweise Payloads, Timeout-Behandlung, gleichzeitige Checkout-Versuche.
Die Lösung: Führen Sie die offizielle UCP-Testsuite (verfügbar unter ucp.dev/testing) vor und nach jeder Veröffentlichung in Ihrer Staging-Umgebung aus. Fügen Sie die Testsuite Ihrer CI/CD-Pipeline hinzu. Die UCP-Zertifizierung wird von großen KI-Agenten-Anbietern zunehmend als Vertrauenssignal herangezogen; die Aufrechterhaltung des Zertifizierungsstatus ist wichtig.