> Documentation index: https://www.xekta.com/llms.txt # Errors > Every XEKTA error has the same shape and says what to do next. The codes a buyer's assistant can meet, and the fix for each. ## The shape ``` { "error_code": "SINGLE_MERCHANT_CART_REQUIRED", "field": "merchant_id", "reason": "A cart can only contain products from one merchant.", "corrective_action": "Create a separate cart for the other merchant or remove existing items from the current cart.", "recoverable": true } ``` | Field | Always there | What it is | | - | - | - | | `error_code` | Yes | A stable code. Branch on this, not on the wording. | | `field` | Yes | The input at fault, or `null`. | | `reason` | Yes | What went wrong, in words. | | `corrective_action` | Yes | What to do next. | | `recoverable` | Yes | `true`: fix the input and retry. `false`: do not retry. | | `example_corrected_call` | Sometimes | A minimal corrected call that shows the shape of the fix. | ## How to recover - `recoverable: true`: fix the input as `corrective_action` says and retry **once** before telling the buyer. - `recoverable: false`: do not retry. Tell the buyer and stop. - If retrying does not fix it, show the buyer the error as it is. Do not paraphrase it away. > [!WARNING] > `example_corrected_call` only shows the shape. For restaurant options it picks the first available choices. Ask the buyer; never send the example as it is. ## Input | Code | Meaning | What to do | | - | - | - | | `INVALID_INPUT` | An input failed validation. | Fix the field named in `field`. | | `MISSING_FIELD` | A required field is absent. For restaurant items, a required option group on `modifiers`. | Add the field. For options, ask the buyer which they want. | | `UNKNOWN_SKU` | The SKU does not exist. | Search again. | | `NO_RESULTS` | Nothing matched. Often a normal answer, not a failure. | Try a broader word. | ## Account | Code | Meaning | What to do | | - | - | - | | `ACCOUNT_SETUP_REQUIRED` | The buyer's phone, terms or card step is not finished. | Give the buyer the link from `corrective_action` exactly as returned, and stop. | | `ROLE_MISMATCH` | The account is not a buyer account. | Give the person the link from `corrective_action`, and stop. | | `VERIFIED_IDENTITY_REQUIRED` | The call needs a signed-in identity and none is available. | Reconnect. There is no `user_id` field to fill in. | ## Safety | Code | Meaning | What to do | | - | - | - | | `RESTRICTED_CATEGORY` | The category is blocked. See [What XEKTA does not do](https://www.xekta.com/docs/not-supported.md). | Offer something from another category, or tell the buyer. | | `RESTRICTED_QUERY` | The search targets a restricted product. | Rephrase, or decline. | | `PROMPT_INJECTION_DETECTED` | Free text contains instructions aimed at the assistant. | Remove them and retry. | ## Shops and stock | Code | Meaning | What to do | | - | - | - | | `SINGLE_MERCHANT_CART_REQUIRED` | The cart would mix two shops. | Make a separate cart for the other shop. | | `MERCHANT_UNAVAILABLE` | The shop is not taking orders right now. | Choose another shop, or try later. | | `CATALOG_BUSY` | Only from `checkout_create`: the shop is updating its catalog. Nothing was charged, no order was created, and the approval still stands. | Retry `checkout_create` in a moment with the same cart. Do not rebuild the cart or ask the buyer again. | | `PRODUCT_UNAVAILABLE` | An offer is no longer purchasable. No order was created. | Rebuild the cart without it, or offer a substitute. | | `INVENTORY_RESERVATION_EXPIRED` | The stock hold ran out. | Place the order again. | ## Payment | Code | Meaning | What to do | | - | - | - | | `CHECKOUT_AUTHORIZATION_FAILED` | No card on file, or the card was declined. `corrective_action` says which. | Call `user.payment_method.setup`, then try again. | | `PAYMENT_RAIL_UNAVAILABLE` | The payment provider could not be reached. | Changing the card does not help. Try again shortly. | ## Sales tax `cart_approve` and `checkout_create` refuse with these codes. `cart_get` and `cart_set_quantity` do not fail: they return the cart with `tax_cents` and `total_cents` set to `null` and a `tax_error` field. | Code | Meaning | What to do | | - | - | - | | `TAX_UNAVAILABLE` | The tax could not be computed. `reason` says whether the tax service did not answer, or the shop is not set up for sales tax yet. | Service did not answer: try again in a minute. Shop not set up: pick another shop. | | `TAX_CODE_MISSING` | Some items have no confirmed tax class. `product_ids` lists them. | Remove those items, or pick another shop. | | `PREPARED_FOOD_UNAVAILABLE` | The shop cannot sell prepared food yet. `product_ids` lists the items. | Remove those items, or pick another shop. Waiting does not fix it. | ## Limits and server errors | Code | Meaning | What to do | | - | - | - | | `RATE_LIMITED` | Too many tool calls in a short time or in one day. Nothing was changed. | Wait `retry_after_seconds`, then retry the same call. Do not loop. | | `SERVER_ERROR` | Something went wrong on XEKTA's side. The answer carries a short `ref`. | Retry once a little later. If it repeats, stop and give the buyer the `ref` for support. | ## Orders | Code | Meaning | What to do | | - | - | - | | `ORDER_MODIFICATION_OUT_OF_SCOPE` | The order cannot be edited after it reached the shop. | Cancel if still allowed, or place a new order. | | `PICKUP_CODE_UNAVAILABLE` | A pickup code could not be issued. No order was created. | `recoverable: true`: retry checkout. `false`: tell the buyer and stop. | ## When the error itself is wrong Every error is recorded on XEKTA's side before the assistant sees it. [`feedback_submit`](https://www.xekta.com/docs/tools/feedback-submit.md) is for the one thing the server cannot see: that a well-formed error was wrong or misleading, or that its `corrective_action` did not work. The full list, including codes only a shop or an operator can meet, is in the MCP resource `xekta://docs/structured-errors`.