Errors

For the full error catalog, envelope shape, idempotency, rate limits, and known limitations, see the canonical page:

📘 API Reference → Errors & Conventions

That page covers everything — the REST envelope, all error names with HTTP codes + recovery strategies, the UCP envelope for protocol-layer consumers, retry patterns with idempotency, and the ?sse=true known limitation.

This page lists patterns that are specifically relevant to agentic flows — extra context for agent builders on top of the canonical reference.

​​ Patterns specific to agentic flows

​​ Stock changed mid-conversation

The classic agentic race. Your agent showed the user a product, the user confirmed, by the time you call complete-order someone else has bought it:

discovery/search → OK
add-line-item    → OK
set-shipping     → OK
complete-order   → 409 NotEnoughStockError

Conversational recovery: re-fetch the product to see current stock, then surface the change as a question:

“Looks like the medium just sold out — they still have a small or large. Want one of those?”

Update the cart with the new variant/quantity, retry complete-order with a new idempotency key (this is a genuinely new attempt with new parameters).

​​ Payment declined mid-conversation

complete-order → 422 CreditCardDeclined

Do not silently retry the same card. Tell the user the card was declined — without leaking the issuer’s reason verbatim (it can signal valid card numbers). Offer a different payment method. If your agent supports PayPal or Klarna, route to express checkout at this point.

​​ Validation error → conversational ask

set-shipping-info → 400 InvalidInputBody
                    "At path: phone — Expected a string with a length between 10 and 13"

The description includes the failing field path. Map it to a natural-language question rather than echoing the technical error:

“What’s the phone number with country code? (10–13 digits)”

​​ Cart became stale (session TTL expired)

Sessions auto-expire after ~1 hour. If your agent has been holding a cart for >1 hour and the session token is rejected:

1. Bootstrap a new session
2. Rebuild the cart (re-call add-line-item for each item)
3. Continue

Carts are not portable across sessions — there’s no “transfer cart” operation. The user-visible cart state needs to be re-built from your agent’s memory.

​​ get-availability not supported by this merchant

Some merchants return 501 NotImplemented on cart/shipments/get-availability. This does not block checkout: get-availability only returns delivery dates, time slots, and pickup locations for scheduled-delivery or in-store-pickup shipments — it never returns shipping methods. Shipping methods always come from cart.shipments[].shipping_method_options, which Firmly populates inline after set-shipping-info. Treat a 501 as “no scheduled-delivery/pickup detail for this merchant” and proceed with the inline methods. See Shipping & Fulfillment.

​​ Agent-specific anti-patterns to avoid

​​ Where to go next

• Errors & Conventions — canonical catalog and recovery patterns
• Consent & Disclosure — what to surface to the user before placing an order