The Lighthouse Score for Agentic Commerce.

When an agent attempts to add an out-of-stock item, the API returns an HTTP 500 Internal Server Error instead of a proper 422 with a machine-readable error body.

HTTP/1.1 500 Internal Server Error
Content-Type: text/html

<h1>Something went wrong</h1>

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": "OUT_OF_STOCK",
  "sku": "AG-TRAIL-42",
  "message": "Item is currently out of stock",
  "restock_estimate": "2026-03-20"
}

Impact: Agents cannot gracefully handle inventory shortages and will retry indefinitely, causing cascading failures.

Fix: Return a 422 status with a JSON body containing the OUT_OF_STOCK error code, the affected SKU, and an optional restock estimate.

Submitting an address outside the supported region silently accepts the order, which later fails during fulfillment with no notification to the agent.

POST /checkout/shipping
{
  "address": "742 Evergreen Terrace",
  "city": "Vancouver",
  "province": "BC",
  "postal_code": "V5K 0A1",
  "country": "CA"
}

HTTP/1.1 200 OK
{ "status": "accepted" }

HTTP/1.1 422 Unprocessable Entity
{
  "error": "UNSUPPORTED_REGION",
  "country": "CA",
  "supported_countries": ["US"],
  "message": "Shipping to Canada is not available"
}

Impact: Orders are accepted but never fulfilled. Agents receive no feedback to suggest an alternative or notify the customer.

Fix: Validate the country field against supported regions and return a 422 with the UNSUPPORTED_REGION code before order creation.

The Idempotency-Key header is accepted but not enforced. Retried payment requests create duplicate charges.

POST /checkout/pay
Idempotency-Key: agent-txn-8a3f2c
{ "amount": 129.99, "currency": "USD" }

→ 200 OK  { "charge_id": "ch_1001" }

POST /checkout/pay
Idempotency-Key: agent-txn-8a3f2c
{ "amount": 129.99, "currency": "USD" }

→ 200 OK  { "charge_id": "ch_1002" }   ← duplicate charge created

→ 200 OK  { "charge_id": "ch_1001" }   ← return original charge

Impact: Network retries by agents result in customers being charged multiple times for a single order.

Fix: Implement server-side idempotency key storage. On duplicate key, return the original response with the same charge_id instead of processing a new payment.

The X-Cache-Age header reports inventory data was last refreshed 47 minutes ago. For high-velocity SKUs, this increases the likelihood of overselling.

Impact: Agents may add items to cart that are already sold out, leading to failed checkouts late in the flow.

Fix: Reduce cache TTL to under 5 minutes for inventory endpoints, or implement a real-time stock reservation system.

The order confirmation endpoint shows elevated response times under simulated agent concurrency.

Impact: Agents with short timeout windows may abandon checkout, resulting in orphaned carts and lost revenue.

Fix: Profile the confirmation endpoint for N+1 queries and consider moving payment processing to an async webhook pattern.