Skip to main content
Error flow: error, diagnose the code, recover or retry Checkout can fail in ways your agent should handle gracefully. Here’s how to handle each one. Every error response has the same shape:
Some errors carry extra fields. The ones below are the most important.

review_changed

The checkout review changed between the last read and the commit. Nothing was placed.
What changed: reason tells you the first thing that moved. changes lists every field that differs. Recovery: read the new review (it’s in the error response), present it to the shopper, and call complete_checkout with the new review_hash and total_minor.

review_mismatch

The review_hash you sent does not match the live review. Nothing was placed.
Recovery: call get_checkout, use the new review_hash and total_minor, and try again.

total_mismatch

The total_minor you sent does not match the live review. Nothing was placed.
Recovery: same as review_mismatch. Call get_checkout and use the latest figures.

commit_unknown

The order was submitted to the merchant, but no confirmation came back. This is the most critical error.
Do not retry. The order may already exist at the merchant. Retrying risks a duplicate order. Recovery:
  1. Call get_order with the order id from the session.
  2. If the order exists and is confirmed, you’re done.
  3. If the status is unknown, wait. AgentMall checks with the merchant and updates the status.
  4. Never call complete_checkout again for this session.

out_of_stock

Returned by create_checkout when an item was removed by the merchant.
Recovery: remove the unavailable items with update_cart, then call create_checkout again. If unavailable_items is missing, call get_cart to see what’s left.

cart_clear_failed

The cart clear stopped partway through. Some items were removed, some were not.
Recovery: call update_cart again. It will retry the clear.

checkout_not_ready

A temporary condition. The checkout page did not load in time.
Recovery: retry once. If it fails again, the browser session may need to be recreated.

sign_in_required

Returned by create_checkout when the merchant session is not signed in.
Recovery: call sign_in with encrypted credentials, then try create_checkout again. Or pass an address directly on update_checkout to check out as a guest.

totals_unstable

The checkout total could not be verified against the line breakdown.
Recovery: retry once. The merchant page may still be loading.

General guidance

  1. Always use the latest review_hash. After any update_checkout or get_checkout, the hash changes.
  2. Show the review to the shopper before calling complete_checkout. The review is the source of truth.
  3. Never retry after commit_unknown. This is the one error where retrying can cause real harm.
  4. Check get_cart after ambiguous errors. When the error doesn’t tell you exactly what’s in the cart, read it.
See Error codes for the full error reference.