> ## Documentation Index
> Fetch the complete documentation index at: https://agentmall.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Handling checkout errors

> Every checkout error your agent can hit, with recovery steps.

![Error flow: error, diagnose the code, recover or retry](https://mintcdn.com/agentmall/ZuoglRqW4CDsIaRs/images/checkout-errors.svg?fit=max\&auto=format\&n=ZuoglRqW4CDsIaRs\&q=85\&s=52577740bd550718c6a81baecce54b51)

Checkout can fail in ways your agent should handle gracefully. Here's how to handle each one.

Every error response has the same shape:

```json theme={null}
{
  "error": {
    "code": "...",
    "message": "..."
  }
}
```

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.

```json theme={null}
{
  "error": {
    "code": "review_changed",
    "reason": "item_unavailable",
    "changes": [{ "field": "items", "before": ["27574659", "585061508"], "after": ["585061508"] }],
    "review": {
      "line_items": [{ "itemId": "585061508", "quantity": 1 }],
      "totals": { "subtotal": 2197, "tax": 181, "total": 2378 },
      "review_hash": "d4e5f6a1b2c3..."
    }
  }
}
```

**What changed:** `reason` tells you the first thing that moved. `changes` lists every field that differs.

| `reason` | What happened | Recovery |
| - | - | - |
| `item_unavailable` | An item was added or removed | Remove it or pick a replacement, re-read the checkout, ask the user |
| `quantity_changed` | Same items, different quantity | Set the quantity with `update_cart`, re-read the checkout |
| `address_changed` | The address on the review is different | Check the address with `update_checkout` |
| `delivery_changed` | The delivery method is different | Pass the method again on `update_checkout` |
| `payment_changed` | A different card is on the order | Pass the card again on `update_checkout` |
| `price_changed` | Only the total moved | Compare the new total with the user's limit |
| `unknown` | No saved review to compare | Call `get_checkout` and present the review again |

**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.

```json theme={null}
{
  "error": {
    "code": "review_mismatch",
    "message": "The review hash does not match. Read the checkout again."
  }
}
```

**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.

```json theme={null}
{
  "error": {
    "code": "total_mismatch",
    "message": "The total does not match the review."
  }
}
```

**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.**

```json theme={null}
{
  "error": {
    "code": "commit_unknown",
    "message": "Order may have been placed. Do not retry. Call get_order."
  }
}
```

**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.

```json theme={null}
{
  "error": {
    "code": "out_of_stock",
    "message": "Item removed by merchant.",
    "unavailable_items": [{ "id": "27574659", "title": "Energizer MAX AA Batteries, 24 Pack" }]
  }
}
```

**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.

```json theme={null}
{
  "error": {
    "code": "cart_clear_failed",
    "message": "Clear stopped partway.",
    "removed": 2,
    "left": 1
  }
}
```

**Recovery:** call `update_cart` again. It will retry the clear.

## `checkout_not_ready`

A temporary condition. The checkout page did not load in time.

```json theme={null}
{
  "error": {
    "code": "checkout_not_ready",
    "message": "Checkout did not open. Retry once."
  }
}
```

**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.

```json theme={null}
{
  "error": {
    "code": "sign_in_required",
    "message": "Sign in first, or pass an address on update_checkout."
  }
}
```

**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.

```json theme={null}
{
  "error": {
    "code": "totals_unstable",
    "message": "Totals could not be verified.",
    "totals": { "subtotal": 1697, "tax": null, "total": 1837, "unreadable": "Est. tax" }
  }
}
```

**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](https://agentmall.mintlify.site/reference/errors.md) for the full error reference.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.