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

# Errors

> Error codes returned by MCP tools and the REST API.

Errors are typed. Prefer the `code` field over parsing `message`.

## Auth and limits

| Code | What it means | What to do |
| - | - | - |
| `unauthorized` | No API key | Add `Authorization: Bearer <key>` |
| `invalid_key` | Unknown key | Check the key with AgentMall |
| `merchant_unavailable` | Only Walmart in beta | Use `mrc_walmart` |
| `rate_limited` | Too many searches | Wait `retry_after_seconds` |
| `daily_limit_reached` | Search cap used | Wait until UTC midnight or ask for a higher cap |
| `provider_unavailable` | Catalog source down | Wait and retry |
| `product_not_found` | Unknown `product_id` / bad URL | Search again |

## Session and sign-in

| Code | What it means | What to do |
| - | - | - |
| `sign_in_unavailable` | No platform Walmart account configured | Guest checkout: pass address + card to `prepare_checkout` |
| `challenge_required` | SMS OTP needed | Collect the code; call `submit_sign_in_otp` |
| `guest_no_saved_addresses` | Guest session has no saved addresses | Pass `address` / `address_vault_ref` to `prepare_checkout` |
| `guest_no_saved_payment_methods` | Guest session has no saved cards | Pass `card` / `vault_ref` / `payment_method_id` |

## Cart

| Code | What it means | Retry? |
| - | - | - |
| `product_not_found` | URL is not a valid Walmart product page | No |
| `already_in_cart` | Use `set_cart_item_quantity` instead | No |
| `quantity_invalid` | Quantity must be a whole number ≥ 1 | No |
| `quantity_above_max` | Quantity at most 12 | No |
| `remove_failed` | Remove control missing or ambiguous | No |
| `unsupported` | One line item per `add_to_cart` | No |

## Checkout and payment

| Code | What it means | What to do |
| - | - | - |
| `review_changed` / `review_mismatch` | Basket changed since review | Call `prepare_checkout` again |
| `total_mismatch` | Total changed since review | Call `prepare_checkout` again |
| `commit_unknown` | Order may or may not have been placed | **Do not retry.** Call `get_order` |
| `invalid_address_field` / `address_incomplete` | Bad or missing address field | Fix the named field |
| `address_undeliverable` | Walmart can't deliver there | Ask for another address |
| `address_not_found` | Address rewritten and not selected | Resend as Walmart writes it |
| `payment_reference_not_found` | Unknown or revoked card | `write_payment_method` or list again |
| `payment_method_expired` | Card expired | Ask for another card |
| `vault_not_configured` | Cards not enabled for this key | Ask AgentMall to enable vault |
| `vault_tokenize_failed` | Card could not be vaulted | Check fields and retry |

## Console API

| HTTP | Code | Meaning |
| - | - | - |
| 401 | `unauthorized` / `invalid_key` | Bad or missing key |
| 404 | `not_found` | Session or order not in this org |
| 503 | `unavailable` | Database / billing read failed |

Full tool inputs: [MCP tools](https://agentmall.mintlify.site/mcp/tools.md). Checkout semantics: [Mandates and approval](https://agentmall.mintlify.site/concepts/mandates-and-approval.md).


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