Common UCP Integration Errors and Troubleshooting Guide for Developers

Last Updated: November 10, 2026 • Autonomous Agentic Commerce Spec v2026-08-25

Production Validated

What this guide covers

Error Code HTTP Status Root Cause Debugging Inspection Point Protocol Resolution Developer Action
ERR_SIGNATURE_MISMATCH 401 Unauthorized. Private key signature does not match public key in trust registry. Inspect @request-target normalization and ES256 curve parameters. Re-sign request ensuring canonical header order per RFC 9421. Verify public key registration in /.well-known/ucp manifest.
ERR_INVENTORY_COLLISION 409 Conflict. Competing agent locked limited stock during two-phase commit. Inspect Redis lock key TTL and allocation ownership. Automatic atomic rollback returning inventory to pool. Implement exponential backoff retry with decorrelated jitter.
ERR_DELEGATION_EXPIRED 403 Forbidden. FIDO AP2 delegation token exceeded 120-second validity window. Check client device system clock drift and token exp claim. Request silent biometric re-attestation from user device. Synchronize NTP servers across application clusters.
ERR_PRICE_BELOW_FLOOR 422 Unprocessable Entity. Agent’s negotiated bid falls below merchant WebAssembly price floor. Inspect custom.price_floor metafield in product catalog. Reject bid with counter-offer threshold payload. Update agent’s algorithmic bidding boundary parameters.
ERR_WEBHOOK_TIMEOUT 504 Gateway Timeout. Merchant webhook listener took >5000ms to acknowledge reservation. Check database query locks and asynchronous queue workers. Idempotent status query before retrying to prevent duplicate lock. Decouple webhook ingestion from synchronous database transactions.

Integrating with the Universal Commerce Protocol (UCP) means connecting distributed systems: your agent, your merchant backends, fulfilment services, inventory systems, payment dependencies, and asynchronous notifications. When something breaks, the symptom can appear far from the cause. A checkout that fails at the last step may have started as stale inventory data. A missing update may be a webhook that never received an acknowledgement. A retry storm may be a handler that was never designed to be re-run safely.

This guide gives you a single, practical framework for diagnosing and resolving the most common UCP integration problems. It is organized by error and fix, not by source document, so each pattern appears once and in full depth. You will find first what is settled about UCP itself, then clearly labeled general engineering patterns you can apply to any distributed commerce integration.

Version note: Google surfaces teach 2026-04-08 versus spec 2026-08-25. Treat Google-published surfaces and the specification as versioned sources that can move independently. Where this guide states a UCP fact, it is limited to settled signals described below. Beyond those settled signals, a normative UCP error catalogue has not been settled. Generic HTTP codes, field names, and envelope shapes discussed elsewhere on the web should not be treated as the settled UCP catalogue. When in doubt, consult the official UCP schema and specification for the exact version you are targeting and validate against that version in your pipeline.

How to use this guide: Start with authentication, because nothing else can be trusted until identity and message authenticity are correct. Then check the small set of settled UCP error signals. Then work through the labeled generic patterns: validate locally, verify identifiers and configuration, make handlers idempotent, acknowledge webhooks fast and process asynchronously, retry only transient failures with backoff and jitter, and observe everything with structured logs, metrics, and traces. Each section below expands those steps in full.

Get authentication right first

Most integration failures that look like business-logic bugs are really authentication or transport trust failures. UCP does not rely on headers alone for trust. If you diagnose payloads, inventory, or webhooks before you have confirmed mutual authentication and message signatures, you will chase false leads.

What UCP requires for trust

Authenticate with mutual TLS against Google UCP Root CAs and verify HTTP message signatures under RFC 9421 with ES256 against the keys advertised in keys[] at https://ucp.goog/.well-known/ucp.json. Do not treat a bearer token, API key, or Authorization header by itself as proof that a message came from UCP, and do not treat possession of such a header as authorization to act on a merchant resource.

In practice this means two independent checks must both pass. First, the TLS layer must authenticate with the correct root trust. Second, the application layer must verify the RFC 9421 signature using ES256 and the current advertised keys. If either check fails, stop and fix trust before debugging payload semantics. Log the verification result, the key identifier that was used, and the timestamp of the key fetch so you can distinguish an expired or unknown key from a genuinely forged request.

Key rotation and caching

Cache the discovery document and keys with max-age=86400 and refetch on unknown kid. When you see a signature with a key identifier you do not recognize, do not immediately reject the traffic as malicious. Your cached keys may simply be stale after rotation. The correct sequence is: note the unknown kid, refetch the discovery document, retry verification once with the fresh keys, and only then treat a continued failure as untrusted.

General API practice — not UCP spec: keep a small, time-bounded negative cache for failed fetches so a transient outage of the well-known endpoint does not cause a thundering herd. Instrument key-fetch latency and failure rate, alert on repeated unknown-kid events after successful refetch, and keep the previous known-good keys available in memory until the fresh fetch is verified. This protects you from a bad deploy that clears the key cache at the same time the network is degraded.

Network reachability for Google traffic

Ensure your infrastructure permits traffic from Google AS15169 and AS396982 and exempts that traffic where your edge would otherwise challenge, throttle, or block automated requests. If your firewall, bot mitigation, or edge policy requires explicit exemptions for Google infrastructure, apply those exemptions rather than attempting to pin individual outbound addresses that can change.

General API practice — not UCP spec: verify reachability in both directions. For outbound calls from your service, confirm DNS resolution, egress firewall rules, and proxy configuration for HTTPS. For inbound notifications to your webhook, confirm the URL is public, uses a valid trusted certificate chain, resolves correctly from external networks, and is not behind a login wall or VPN. Test with the minimal possible handler that logs headers and timestamps and returns success, then add complexity back incrementally.

Transport profiles

REST is the default, MCP is Beta. Build and troubleshoot against the profile you actually negotiated. Do not assume behavior from one profile applies to the other. When you report an issue, record which profile, which specification date, and which endpoint configuration was in use, so you do not mix observations from different profiles or versions.

Settled UCP error signals: what you can treat as UCP fact

Beyond authentication, only a small set of error signals is settled as UCP fact in this consolidation. Everything else in this guide is explicitly labeled as generic engineering advice. Keeping that boundary sharp prevents you from coding against field names, codes, or envelopes that were never settled.

Availability: out_of_stock

The merchant as Merchant of Record must return out_of_stock when the item is unavailable. Treat this as the authoritative availability signal. When you receive it, do not retry the same reservation against the same offer as if it were transient. Surface the unavailability, refresh your view of inventory, and offer an alternative path such as a different offer, a back-order flow if your business supports it, or a clear message to the user.

To diagnose an unexpected out_of_stock, work backward in full depth. First, confirm you requested the correct offer and quantity and that your request reflects the latest user intent. Second, cross-reference your backend inventory at the exact timestamp of the request, including reservations, holds, safety stock, and channel-specific allocations that may not be visible in a single stock count. Third, check whether a real-time update was sent but not yet processed, and whether a periodic full refresh is needed to correct missed updates. Fourth, review whether your own caching or feed delay created the appearance of availability that no longer existed. Event-driven updates on every inventory or price change, supplemented by periodic full refreshes and alerts when observed availability diverges from internal systems, keep this signal accurate.

Address validation signals

Address validation signals are settled as distinct from general availability or transient errors. When an address cannot be delivered to or cannot be verified, do not treat it as a retryable server problem. The fix is to correct the data, not to resend the same data more aggressively.

In full depth: capture the exact address as sent, including normalization your system applied before sending. Compare what the user entered with what was transmitted. Check for truncation, missing apartment or suite lines, incorrect postal code formatting, and country-specific field requirements. Prompt for a corrected address with the specific field highlighted, offer verified alternatives where available, and log the original and corrected forms with a correlation identifier so you can see whether the same malformed pattern recurs across many orders.

Recoverable severity

Recoverable severity is settled as a signal that distinguishes conditions the caller may be able to resolve by correcting the request or taking a defined next step from conditions that require a different path. When you receive a recoverable indication, read it as guidance to change something — data, state, or sequence — rather than as permission to retry identically.

Diagnose recoverable conditions by isolating the layer. Reproduce with the smallest possible request. Validate the payload locally against the versioned schema. Verify identifiers and configuration. Test your fulfilment or webhook handler in isolation. Examine backend logs for stack traces and dependency failures. Form a single hypothesis, change one thing, and retest. Repeat until the recoverable condition clears or is reclassified as a different settled signal such as out_of_stock.

Rate limiting: 429 Too Many Requests and Retry-After

429 exists as a spec Protocol Error (MCP -32000). On 429 and 503, a Retry-After or retry_after indication SHOULD be present. Honor it when it is present. An example value of 60 is illustrative only, not a UCP quota or guarantee.

When you receive 429, do not immediately retry at full speed. Pause for the duration indicated by Retry-After or retry_after if present. If it is absent, fall back to the labeled generic backoff pattern described below. Separate rate-limited traffic from other transient 5xx traffic in your metrics so you can see whether you are being throttled, whether a dependency is unhealthy, or whether both are happening at once. Review your sending pattern for accidental retry amplification: a single user action should not generate multiple concurrent mutating calls, and a webhook redelivery should not trigger a new upstream reservation.

General API practice — not UCP spec: no tiers, no per-endpoint limits, no requests-per-minute or requests-per-second numbers, no X-RateLimit header conventions, no suspension rules, and no token-bucket or leaky-bucket mandates are stated here as UCP facts. Any client-side pacing you implement is author practice for politeness and stability, not compliance with a published UCP quota. Keep that pacing configurable, conservative, and observable, and never present your chosen numbers as UCP values.

Validate payloads locally before you send

General API practice — not UCP spec: UCP is strongly typed in intent. The most reliable way to avoid rejections is to validate strongly-typed payloads locally before sending, using the official schema for your target version as the source of truth.

What to check

  • Required fields: confirm every required field for the operation and version is present. Do not guess across versions; download the schema for the version you ship.
  • Data types: confirm strings, integers, numbers, booleans, arrays, and objects match the schema. Pay special attention to nested objects where a single wrong type deep in the tree can reject an otherwise correct request.
  • Allowed values: confirm enumerated values match exactly, including casing. Do not invent values or carry values from a different API that uses different names.
  • Structure: confirm nesting, cardinality, and field placement. A field in the wrong object is a missing field in the right object.
  • Formats: confirm date, time, currency, and identifier formats match the specification, including ISO 8601 where required and ISO 4217 for currency codes where applicable.

How to check in depth

General API practice — not UCP spec: integrate validation libraries such as ajv or jsonschema into development and into your continuous integration pipeline. Validate example payloads on every pull request, validate generated payloads against the latest pinned schema before deployment, and fail the build on schema violations. Keep version-controlled copies of the schemas you validate against so a specification update does not silently change what passing means.

When a payload is rejected, isolate and simplify. Reduce a large feed or order to a single minimal item that reproduces the failure. Add complexity back one field at a time until the rejection returns. Log the full request you sent, the full response you received, timestamps, and a correlation identifier. Compare the logged payload byte-for-byte with what your validator approved to catch serialization, defaulting, or middleware transformations that alter the payload after validation.

Verify identifiers, URLs, and configuration

General API practice — not UCP spec: a large share of not-found and mismatch problems reduces to a wrong identifier, a wrong path, or a resource that was never created in the environment you are calling.

Step-by-step checks

  • Copy identifiers exactly: identifiers are case-sensitive and must match exactly. Check for truncation, whitespace, URL-encoding issues, and confusion between similar identifiers such as test versus production orders.
  • Confirm existence before mutation: when an update fails, retrieve the current representation first and confirm the resource exists and is visible to the credentials you are using. Confirm you are in the expected project and environment.
  • Confirm the path and method: verify the endpoint path, HTTP method, and content type against the documentation for your version and profile. Verify webhook registration points to the exact public URL you intend, including scheme, host, path, and trailing slash behavior.
  • Confirm creation completed: if a subsequent read or update cannot find a resource, verify the original creation actually succeeded and was committed. Check for an asynchronous creation that had not yet completed when the follow-up call was made.

For state-sensitive updates, fetch current state before mutating and avoid duplicate processing. Read the resource, decide whether the intended transition is valid from the observed state, then apply the change. If two writers can act concurrently, serialize access to the same logical resource in your own system and design updates to be safely reappliable so a retried request does not corrupt state.

Design idempotent handlers and deduplicate safely

General API practice — not UCP spec: design idempotent handlers, use unique request identifiers, store and check idempotency keys, deduplicate server-side, and make store-plus-apply atomic.

Why this matters

Distributed commerce retries. A handler that creates a second order when the same logical request arrives twice will eventually create duplicates, no matter how reliable the network appears during testing. The fix is to make repeated delivery of the same logical operation have the same effect as a single delivery.

Full pattern in depth

  • Generate a stable key per logical operation: use a UUID or a hash of the canonical request for the specific creation or update attempt. Reuse the same key across retries of that same attempt. Never reuse the same key for different logical operations.
  • Store and check before applying: before processing, look up the key in a durable processed-requests store. If the key has already been successfully processed, return the prior successful result without re-executing business logic.
  • Make store and apply atomic: commit the key and the business effect in a single transaction where possible. This prevents a crash between creation and key recording from leaving a half-applied operation that will be duplicated on retry.
  • Handle concurrent arrivals: guard against two simultaneous deliveries of the same key both passing the existence check. Use a unique constraint or conditional write so only one writer wins, and the loser reads back the winner’s result.
  • Expire and audit: retain keys long enough to cover the maximum realistic retry and redelivery window. Log key, timestamp, input hash, and outcome for every decision to process or deduplicate.

Apply the same discipline to webhook handlers. Webhook redelivery is normal. A webhook handler that is not idempotent will double-count carts, orders, or cancellations. Check the delivery identifier, acknowledge quickly as described below, and process exactly once in effect even if delivered more than once in fact.

Acknowledge webhooks fast, then process asynchronously

General API practice — not UCP spec: a webhook endpoint must return an immediate 2xx and then process asynchronously. Blocking the acknowledgement while doing slow work causes timeouts, retries, and duplicate notifications.

Robust receiver in depth

  • Return 2xx immediately on receipt: validate transport and signature, persist the raw payload with headers and timestamp, enqueue for background processing, and return success. Do not perform database writes across multiple services, inventory checks, pricing calculations, or external calls before responding.
  • Verify authenticity correctly: verification is mTLS plus RFC 9421 ES256 against keys[] at https://ucp.goog/.well-known/ucp.json, not a shared secret. Do not deploy shared-secret webhook verification as UCP fact. If signature verification fails after a fresh key refetch on unknown kid, reject and log with full context.
  • Check URL, firewall, and certificate: confirm the registered URL is exact and public, the certificate chain is valid and unexpired, and Google AS15169 and AS396982 traffic is exempted from challenge or block. Look in server, proxy, and edge logs for rejected connections that never reached your application.
  • Process from a queue: hand off to a durable queue and worker pool. Workers should be idempotent, retryable with backoff, and observable. Track queue depth, processing latency, and poison messages that repeatedly fail.
  • Monitor and alert: track webhook receipt rate, acknowledgement latency, verification failure rate, processing success rate, and redelivery rate. Alert on a drop in receipts, a spike in verification failures, or growth in unprocessed backlog.

To debug a silent webhook, start at the edge and move inward. Confirm registration, confirm DNS and certificate, confirm a request reaches your edge by checking edge logs, confirm it reaches your application by checking application logs, confirm you returned 2xx within the expected window, and only then debug business logic. Simulate delivery in isolation with a minimal payload to separate transport problems from processing problems.

Retry only transient failures with exponential backoff and jitter

General API practice — not UCP spec: use exponential backoff with jitter for transient 429 and 5xx conditions. Do not retry validation, authentication, or settled business signals such as out_of_stock as if they were transient.

What to retry and what not to retry

  • Retry with backoff: transient unavailability and throttling where the system explicitly invites a later retry, honoring Retry-After or retry_after when present on 429 or 503.
  • Do not retry identically: malformed payloads, unknown identifiers, failed trust verification, and settled unavailability. These require a corrected request, corrected configuration, or a different business path.
  • Bound the effort: set a maximum number of attempts, a maximum elapsed time, and an overall deadline. Log every attempt with attempt number, delay, and outcome. Surface a clear failure to the caller or operator when the budget is exhausted rather than retrying forever.

Backoff in depth

General API practice — not UCP spec: increase the delay between attempts exponentially, add a small random jitter to avoid synchronized retries from many clients hammering the server at the same instant, and cap the maximum delay. Distinguish retryable from non-retryable outcomes before sleeping: only sleep and retry when the outcome is classified as retryable. Include idempotency keys on retried mutating calls so a retry that actually succeeded on the server side does not create a duplicate. Queue work and degrade gracefully when the downstream remains unavailable: accept the order for later processing where your business rules allow it, notify the user honestly, and reconcile when health returns.

Optimize slow handlers that cause timeouts rather than masking them with more retries. Profile database queries, ensure indexes exist, avoid N+1 query patterns, cache expensive computations and external responses, minimize and parallelize external calls with aggressive timeouts and circuit breakers, and move long-running fulfilment work off the synchronous path. A handler that consistently responds quickly rarely needs to be retried.

Observe everything: structured logging, metrics, and tracing

General API practice — not UCP spec: log full request and response context with correlation identifiers, measure rates and latencies, and trace distributed flows. You cannot fix what you cannot see.

Structured logging with correlation

Log every UCP interaction as structured JSON: timestamp, correlation or request identifier, profile and version, operation name, request payload, response payload and outcome, verification result and key identifier, latency, and relevant internal state such as order and offer identifiers. Sanitize secrets and payment data before persistence. Correlate with request and correlation identifiers across client, server, queue, and webhook so a single transaction can be followed end to end.

General API practice — not UCP spec: an author workflow is to filter a centralized log explorer for errors, search by correlation identifier or order and offer identifiers, and inspect the structured payload for the exact failure. Keep that workflow as labeled author practice, not as a claim about specific UCP log names, resource types, or field shapes. Do not code alerts against unsettled log names or payload paths.

Metrics and tracing

General API practice — not UCP spec: instrument request and error rates by operation and outcome, outbound call latency and inbound webhook processing latency, queue depth and worker lag, verification failure rate, and retry and deduplication rates. Alert on elevated error rates or latency spikes. Use distributed tracing such as OpenTelemetry to visualize a transaction as it moves through your services and to pinpoint bottlenecks behind timeouts. Use application performance monitoring to find slow queries, blocking I/O, and CPU-bound sections.

Mock and isolated tests

General API practice — not UCP spec: build a lightweight local mock that simulates the endpoints you call and the notifications you receive. Program it to return specific success and failure shapes so you can exercise validation, idempotency, retry, and webhook paths without network dependence. Write unit tests for request builders and response parsers, integration tests for handlers against the mock, and end-to-end tests for full workflows including edge cases such as duplicate delivery, slow dependencies, and conflicting updates. Keep mocks and test fixtures versioned alongside the specification version they emulate.

A systematic workflow: reproduce, isolate, hypothesize, retest

General API practice — not UCP spec: follow the same disciplined sequence for every failure so results are comparable and fixes are verifiable.

  • Reproduce the issue: establish the exact sequence that triggers the failure. Record inputs, configuration, version, and environment. If it is intermittent, capture frequency, timing, and any correlation with deploys, traffic spikes, or dependency incidents.
  • Check logs first: start with centralized logs for the correlation identifier. Determine whether the failure is in your request construction, in trust verification, in fulfilment processing, or in webhook delivery before changing code.
  • Isolate the layer: test each layer independently. Validate the payload locally against the schema. Send the same payload directly to your fulfilment or webhook handler bypassing the network path. Replay a captured payload to see whether the handler behaves deterministically.
  • Validate payloads and configuration: compare logged payloads against the versioned schema, verify identifiers and URLs, and verify authentication configuration including roots, keys, cache age, and exemptions for Google traffic.
  • Examine backend and dependency logs: look for stack traces, database errors, payment gateway rejections, shipping API failures, and circuit-breaker events. Confirm external dependencies were healthy at the time of failure.
  • Formulate a single hypothesis: state what you believe is wrong, what evidence supports it, and what would disprove it. Change one thing at a time.
  • Implement and retest: apply the fix, rerun the minimal reproduction, then rerun the broader suite including idempotency, retry, and webhook redelivery cases. Monitor metrics after deployment to confirm the failure class actually declined.

Proactive measures that prevent most incidents

General API practice — not UCP spec: prevention is cheaper than debugging. Automate validation in continuous integration so invalid payloads never ship. Maintain comprehensive unit, integration, and end-to-end coverage for creation, update, fulfilment, and notification flows. Version-control API definitions, mocks, and fixtures and keep them synchronized with the specification version in production.

General API practice — not UCP spec: design for graceful degradation. Decide in advance what happens when a critical call fails: retry with backoff if transient, queue for later where business rules allow, offer a clear alternative to the user, and emit an operational alert. Cache judiciously to reduce redundant work, but understand cache lifetimes so temporary discrepancies do not become persistent divergence. Review performance budgets regularly so handlers remain fast enough to avoid timeouts as traffic grows.

General API practice — not UCP spec: keep documentation and runbooks current. Record the profile and version in use, the authentication and key-refresh procedure, the settled signals you handle and how, the generic patterns you apply and where, and the dashboards and alerts that cover each failure class. Review release notes before upgrades and test new versions in isolation before promoting to production. A stable UCP integration is not a single fix but a steady practice: correct trust, small settled signal set, labeled generic patterns applied consistently, and observability that lets you see the next failure clearly.

Frequently Asked Questions

Why does UCP return 401 ERR_SIGNATURE_MISMATCH even when my API key is valid?

UCP does not rely on static API keys; it enforces RFC 9421 HTTP Message Signatures. This error occurs if signed headers (like date or digest) are modified by intermediate proxies or load balancers in transit.

How do developers handle concurrent inventory race conditions in high-traffic sales?

Implement distributed locks with a 45-second TTL using Redis Redlock or PostgreSQL row locks, ensuring that when an agent reserves an SKU, competing requests receive an immediate 409 Conflict with an estimated retry window.

What is the required timeout threshold for UCP webhook acknowledgments?

UCP endpoints enforce a strict 5,000ms timeout window. Webhook receivers must respond with HTTP 200 within this budget, deferring heavy database writes and third-party syncs to background workers.


Posted

in

by

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *