Skip to main content
When Agentcard cannot do what a call asks, it refuses with a code that names what went wrong. A refusal charges nothing, and the message says so whenever a payment was about to happen. Read code to decide what to do next. The wording of the message is written for you to read and can change, so never match on it. A refusal is different from a declined purchase. A purchase Agentcard tried and could not finish is an answer, not an error: its status is declined, a decline_code says why, and reply explains it to the shopper. Read a declined answer covers those.

See how a refusal arrives

The codes are the same in the SDK, the MCP server and the API. Only the way a refusal reaches your code differs.
A call on AgentcardClient, such as agentcard.conversation() or agentcard.order(), throws an AgentcardApiError:
orders.ts
The buy tool answers some refusals for the model instead of failing. cart_changed, nothing_to_confirm, conversation_closed, a changed delivery address, cart_not_ready, turn_in_progress, pick_not_found and store_pick_not_found come back as status: 'needs_input', with the code in error_code and a reply that tells the model what to do:
A shopper not yet connected to your company comes back as status: 'needs_card', with the link to add a card. Every other refusal fails the tool call: your model reads the message with its links taken out, and the error’s cause holds the AgentcardApiError.The client adds codes of its own, for a call that never got an answer it can read:On this page, external_user_id is the externalUserId you pass, and conversation_id is the answer’s conversation_id.

Find the code

Each code has its own section below, with the body as the API sends it. Two words recur: a conversation is one purchase, from the shopper’s first request to the order, and a cart’s hash is a short code that names this exact cart at this price, which a confirm sends back. A code your calls cannot cause never reaches you. A call that never sends items or return_url, for example, never meets their refusals.

Name the shopper

Your company’s credentials buy for many shoppers, so every call says which one with external_user_id, your own id for that shopper. A call with no shopper is refused:
Send the same id for the same shopper on every call, including calls about a purchase already under way. A shopper who never made a purchase request in this mode is refused on every other call:
Send a purchase request with what the shopper asked for, and Agentcard adds them on that request. Shoppers in the sandbox are separate from live ones, so a shopper you tested with starts again in live mode. A call that names the shopper twice is refused:
Send external_user_id alone, or user_id alone. A call made with one shopper’s own access token that names another shopper is refused:
Call with your company’s credentials to buy for another shopper. An external_user_id that two shoppers carry is refused with both of them:
Send the right shopper’s id from user_ids as user_id, and give each shopper their own id from then on.

Fix the request

A field missing or in the wrong shape is refused with invalid_request, and error names the field:
Send pick as { "product_id": "..." }. Other values of error you can meet:
A list of products sent as items is refused:
Describe what the shopper wants in ask, such as "a 40 oz Stanley Quencher tumbler". A delivery_address missing a part is refused:
Send street, city, state and zip, and country for an address outside the US. A return_url, the page the shopper comes back to after a step, is refused unless your app registered it:
Send one of the return addresses you registered for your app, exactly as registered.

Continue the right conversation

A conversation_id that is not this shopper’s is refused:
Check that the call names the same shopper that started the conversation, or leave out conversation_id to start a new one. A conversation that has ended is refused:
Start a new purchase. A conversation started under one thread_id, the id of a chat in your app, is refused under another:
Send the conversation_id that chat’s own requests returned, or resume: true with this thread_id. A pick of a product that is not in the conversation’s latest search is refused, and nothing is added:
Send the shopper’s words again without the pick, and Agentcard searches again. A pick of a store answers store_pick_not_found the same way. A pick of a product Agentcard can show but not buy is refused:
Ask the shopper to pick a product at another store. A confirm sent when Agentcard’s last message asked the shopper a question about something other than the cart is refused:
Send the shopper’s yes as their words, not as a confirm, so it answers the question.

Confirm the cart that stands

A confirm names the cart the shopper said yes to. A confirm before any cart is refused:
Build the cart with the shopper’s words, show it to them, then confirm it. A confirmed cart that no longer matches, because an item, a quantity, a price, a tip or a fee changed, is refused:
Show the shopper the carts in the refusal, and confirm them on the shopper’s new yes. With carts at several stores, one cart that no longer matches refuses them all, so confirm every cart you still mean to buy. A confirm after the delivery address changed is refused:
Send the new address with the shopper’s words, show the shopper the cart built for it, then confirm that cart. A confirm while the store is still building the cart is refused:
Wait for the message with the cart’s total, show it to the shopper, and confirm on their yes. Agentcard does not send an answer whose cart it could not save, and refuses instead:
Read the conversation, show the shopper its cart, then confirm that cart.

Pay at a store’s checkout

Some stores are bought through their own checkout page, which Agentcard fills in. The shopper pays there with the card saved in the Vault, Agentcard’s page where the shopper saves their card and approves a payment. A confirm of such a cart without payment_source is refused:
Send the same confirm with "payment_source": "vault". In the sandbox, a shopper with no test card saved is refused at the confirm:
Send the shopper a link to the Vault, have them save a test card, and confirm again. Test in the sandbox shows the steps. The store’s checkout can end before the payment. Each of these refusals means nothing was charged and the cart is gone:
Send the shopper’s request again to build a fresh cart. A confirm that arrives while the store’s checkout is still opening is refused:
Send the same confirm again in a few seconds. A store total that moved after the shopper said yes stops the payment before Agentcard presses Pay:
Ask again for a fresh cart, and show the shopper its new total before they say yes. A store whose payment form Agentcard cannot type a card into safely is refused before any card goes in:
Offer the shopper the same product at another store. The store list marks such a store with supported_reason: "gate_refused", which means Agentcard cannot pay at its payment form, as Check where Agentcard can pay shows. A store that cancels orders Agentcard places as a guest, without a store account, is refused:
Offer the shopper another store. A payment Agentcard cannot confirm either way is refused, and it may have gone through:
Do not buy the same product again. Tell the shopper Agentcard is checking with the store, and wait for the message that reports the order. A live account that cannot pay at a store’s own checkout yet is refused:
Contact Agentcard to turn on live orders at stores’ own checkouts. A shopper can pay with their Stripe Link wallet, as Pay with Stripe Link shows. A Link confirm missing a field is refused:
Send conversation_id, and link_payment with its spend_request_id, amount_cents and currency. A cart Link cannot pay is refused:
Cancel the Link payment, and offer the Vault for that cart. Link pays nothing in the sandbox, so every Link confirm there answers this. A Link payment smaller than the store’s total, or in another currency, is refused:
Ask the shopper to approve the cart’s total in Link, then confirm again. A checkout that had to start again at a new total is refused:
Ask again for a fresh cart, and show the shopper its total. After a Link confirm, your server sends the shopper’s Link approval, encrypted, to Agentcard, as the Link encryption guide shows. That call has four refusals:
Post to the approval_id the confirm returned, with the same shopper’s external_user_id.
Read the conversation to learn how the order went.
Confirm the cart again, and send the encrypted approval before the seal_by deadline the new confirm returns.
Encrypt the approval again with the key whose id the confirm returned as key_id.

Bring back a saved cart

A call that names a saved cart can be refused three ways:
Leave out the saved cart and send the shopper’s request again to start a new cart.

Find an order

A read of one placed order names it by order_id. An order_id that is not this shopper’s is refused:
Send the order_id the order.placed event carried, with the same shopper’s id. An order number two stores share is refused with both stores:
Send the same read again with merchant set to one of the listed stores.

Retry when Agentcard is busy

Agentcard answers one call at a time in each conversation. A call sent while the last one is still running waits, then is refused:
Wait for the last call’s answer, or read the conversation until turn_in_progress is false, then send the call again. A short outage is refused, and nothing ran:
Send the same call again after a few seconds. Give Agentcard the request_id if it keeps failing.

Read a declined answer

A purchase Agentcard tried and could not finish answers with status: "declined" and a decline_code. reply explains it to the shopper. A sandbox confirm declines this way on purpose:
Other values name the store’s own reason, such as a sold-out item. Show the shopper reply, and send their answer as the next message.
The buy tool reads two of these for you. vault_approval_required arrives as status: 'approval_sent', and the approval link goes to sendLink. A shopper with no card arrives as status: 'needs_card', with the add-a-card link.