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

# Error Codes

> Every error code with its HTTP status, meaning, and recovery.

Every error has a stable code, an HTTP status, and a message. Codes are never renamed.

Both MCP and REST return the same codes. MCP errors are in the `error` field of the tool result. REST errors are in the JSON body:

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

## Auth

| Code | HTTP | Meaning | Recovery |
| - | - | - | - |
| `unauthorized` | 401 | No key on the request | Add `Authorization: Bearer <key>` |
| `invalid_key` | 401 | Key not recognised, revoked, or mistyped | Check the key with the AgentMall team |

A key that was sent but is wrong is always `invalid_key`, never `unauthorized`.

## Rate and cap

| Code | HTTP | Meaning | Recovery |
| - | - | - | - |
| `rate_limited` | 429 | Over 15 requests per second for this key | Wait `retry_after_seconds` |
| `daily_limit_reached` | 429 | Today's search allowance is used up | Wait until UTC midnight, or reply to your welcome email for a higher cap |

The 429 response includes a `Retry-After` header. The body includes `retry_after_seconds`. `daily_limit_reached` also includes `used_today` and `daily_cap` (MCP) or `usedToday` and `dailyCap` (REST).

## Session

| Code | HTTP | Meaning | Recovery |
| - | - | - | - |
| `session_not_found` | 404 | No cart with that id | Use the `id` from `create_cart` |
| `session_expired` | 410 | Cart timed out, was cancelled, or was checked out | Start a new cart with `create_cart` |

## Catalog

| Code | HTTP | Meaning | Recovery |
| - | - | - | - |
| `invalid_input` | 400 | Missing or invalid required field | Check the tool docs for required inputs |
| `merchant_unavailable` | 400 | Merchant not supported | Use an id from `list_merchants` |
| `provider_unavailable` | 503 | Search provider is down | Wait and retry |
| `catalog_unavailable` | 400 | That source is not configured | Use the default source or `"merchant"` |

## Cart

| Code | HTTP | Meaning | Recovery |
| - | - | - | - |
| `quantity_invalid` | 400 | Not a whole number of at least 1 | Fix the quantity |
| `quantity_above_max` | 400 | Over 12 | Reduce to 12 or fewer |
| `already_in_cart` | 400 | Same product listed twice | Put the quantity on one line |
| `option_required` | 400 | A size, colour, or pack is not chosen | Send `options` with the choice. The error lists the available combinations. |
| `option_not_found` | 400 | That option choice is not on the product | Check `get_product` for valid options |
| `product_not_found` | 400 | The URL is not a product page | Use a product URL from this merchant |
| `product_unavailable` | 400 | Merchant will not sell this item | Remove it from the cart |
| `merchant_blocked` | 403 | Bot detection triggered | Wait and retry |
| `cart_clear_failed` | 500 | Cart clear stopped partway | Call the same operation again to continue clearing. The error includes `removed` and `left`. |
| `timeout` | 504 | Add took too long | Call `get_cart` to check whether the item landed, then retry if it did not |

## Sign-in

| Code | HTTP | Meaning | Recovery |
| - | - | - | - |
| `sign_in_failed` | 400 | Credentials were rejected | Retry once |
| `sign_in_unavailable` | 400 | No encrypted account on a platform cart | Create a shopper cart instead |
| `credentials_required` | 400 | No encrypted merchant login is configured | Collect credentials first |
| `challenge_required` | 200 | The merchant needs an SMS code | This is a result, not an error. Call `submit_sign_in_otp` with the code. |

`challenge_required` is returned as a successful result with `status: "challenge_required"`. It means sign-in started but needs a second factor.

## Checkout

| Code | HTTP | Meaning | Recovery |
| - | - | - | - |
| `cart_empty` | 400 | No items in the cart | Add items with `update_cart` first. Do not retry. |
| `checkout_not_ready` | 400 | Checkout page did not open | Retry once |
| `sign_in_required` | 400 | Merchant requires sign-in | Call `sign_in`, or pass an address on `update_checkout` |
| `out_of_stock` | 400 | Merchant removed an item from checkout | Remove the items in `unavailable_items`, then retry |
| `totals_unstable` | 400 | Checkout total could not be verified against the line breakdown | Retry once |
| `not_on_review` | 400 | No open checkout | Call `create_checkout` first |
| `review_unreadable` | 500 | The review page could not be read | Retry |
| `invalid_input` | 400 | Missing address, method, or card | Pass at least one of `fulfillment.address`, `fulfillment.method`, or `payment.instruments` |
| `invalid_address` | 400 | Non-US address | Use a US postal address |
| `delivery_method_not_found` | 400 | Invalid method id | Use an id from `fulfillment.methods` in the checkout |
| `address_vault_failed` | 500 | Address could not be saved | Retry |
| `vault_tokenize_failed` | 500 | Card token could not be saved | Retry |

## Commit

These codes come from `complete_checkout`. They determine whether the order was placed.

| Code | HTTP | Meaning | Recovery |
| - | - | - | - |
| `review_changed` | 409 | The checkout changed since approval | Nothing was placed. Read the new checkout and confirm again. The error includes `reason`, `changes`, and the live `review`. |
| `review_mismatch` | 409 | `review_hash` does not match | Nothing was placed. Call `get_checkout` and use the new hash. |
| `total_mismatch` | 409 | `total_minor` does not match | Nothing was placed. Call `get_checkout` and use the new total. |
| `review_required` | 400 | Missing `review_hash` or `total_minor` | Pass both fields |
| `commit_unknown` | 500 | The order may have been placed but no confirmation was received | **Never retry.** Call `get_order`. AgentMall is checking with the merchant. |
| `checkout_not_ready` | 400 | Checkout did not open | Retry once |
| `checkout_cancel_failed` | 500 | Browser did not leave checkout | Retry |

> [!WARNING]
>
> `commit_unknown` means the order submission may have reached the merchant. Do not call
> `complete_checkout` again. Call `get_order` to check the outcome.

## Order

| Code | HTTP | Meaning | Recovery |
| - | - | - | - |
| `order_not_found` | 404 | No order with that id | Use the `order.id` from `complete_checkout` |
| `order_unreadable` | 500 | The order exists but the page could not be read | Retry later |
| `operator_unavailable` | 503 | Operator is down | Retry later |

***

Codes are stable. New codes may be added, but existing codes are never renamed or removed.


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