Reference

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.

View as Markdown

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