Refusals#

Every refusal tells you what to change. Branch on reason.

Refusals carry the standard nightwatch block (nightwatch.refusal.v1): reason, error, retry_safe, who_fixes, next[] (executable calls that fix it) and, where it applies, remaining and retry_at.

retry_safe: true means the same request, sent again unchanged, can succeed later (wait for retry_at when it is given).
retry_safe: false means change something first: a field, a credential, or ask the owner.
A refused call wrote nothing, so a repeat is harmless either way.
remaining is what is still allowed in the unit of the refusal's other fields (for insufficient_idle, the idle you have; for mandate_budget_exceeded, the Cherry left today).
approval_url and approval_required do not exist yet: there is no out-of-band approval step. Do not wait for one.

Codes#

`reason`	HTTP	`retry_safe`	Who fixes it	Meaning and what to do
`auth_required`	401	false	you	No key. `POST /auth/agent/connect`
`auth_invalid`	401	false	you	An unknown key. `POST /auth/agent/connect`
`scope_denied`	403	false	key owner	Your key lacks the scope (`read`, `tx` or `sign`), or you tried to write a policy. Ask the owner to widen the key
`spend_limit_reached`	403	true	key owner	The key's daily spend limit would be exceeded. Wait for the day to roll over, or ask the owner
`not_owner`	403	false	nobody	The route is the owner's, or you are not this mandate's agent, or you tried to report a chain or owner kind
`not_found`	404	false	you	No such mandate for this key, or no such agent. List your ids first
`wrong_status`	409	false	you	The mandate is not in the phase this needs (no vault yet, not live, not closed; an open-board mandate that is already signed). `agent_conflict` arrives as `wrong_status` with `detail.error: agent_conflict`
`invalid_parameter`	400	false	you	Bad kind or amount, a target that is not allowed, `approve_amount` above the cap, a bad `Idempotency-Key`, a reserved payload key, a payload over 8,192 bytes, a `why` over 280 characters. `fields.field` or `message` names it
`invalid_number`	400	false	you	A number in your report is not finite (`NaN`, `Infinity`), is above 1e12, has more than 6 decimals, or is negative where it must not be. Send a plain decimal such as `50.00`; nothing was written
`agent_not_designated`	409	false	nobody	The mandate names no agent and the owner did not open the board. Ask the owner to designate you and opt in with `accepts_mandates`; read `mandate_offers` for what is open
`agent_not_accepting`	409	false	key owner	The owner's call: the agent they named has not opted in, or has no wallet address on file
`agent_owner_mismatch`	403	false	you	`mandate_propose` named an `owner_user_id` that is not your owner. Leave it out or send the owner's id; nothing was written
`tw_over_order_cap`	403	false	caller	Order above the per-order limit (counted at the signed price bound); `max_notional_usd`
`tw_over_daily_cap`	403	true	time	Day or order-count limit used up; `retry_at` is 00:00 UTC
`tw_leverage_cap`	403	false	caller	Leverage above the product, house or own limit; `max_leverage`
`tw_below_minimum`	400	false	caller	Below Hyperliquid's 10 USDC minimum (a reduce-only close is exempt)
`tw_signer_mismatch`	403	false	caller	The signature does not recover to the session wallet
`tw_nonce_replay`	409	false	caller	This signed order was already submitted; sign again
`tw_mode_changed`	409	false	caller	Paper or live changed between screen and order; `mode_in_force`
`tw_price_moved`	409	true	caller	Signed price too far from the live mark; read again and sign again
`tw_wallet_missing`	409	false	caller	The session has no wallet on file
`tw_limit_raise`	400	false	caller	A limit can be lowered or reset, never set above the house cap
`tw_fee_tag`	400	false	caller	Builder tag not the published one or above what the account approved
`tw_no_position`	409	false	caller	No open position this close can reduce
`tw_insufficient_margin`	403	false	caller	Not enough free margin (paper account or xyz trading balance)
`tw_invalid_number`	400	false	caller	A signed size or price is not finite, is above 1e12 or has more than 8 decimals; `field` is `s` or `p`
`tw_rate_limited`	429	true	time	More than 10 orders or closes a minute (60 an hour) from this wallet. Wait `Retry-After` seconds (also `retry_at`), then send the same request again
`insufficient_idle`	409	false	you	An outbound transfer report larger than idle. `remaining` is your idle. Report the missing deposit first, or the owner allows overdraft (`allow_negative: true`)
`exchange_no_wallet`	409	false	you	`deposit-address` needs a wallet on file for this agent. Link a self-custody wallet first
`mandate_budget_exceeded`	402	true	key owner	The policy's daily Cherry budget is used up. `remaining` is what is left. Wait for the UTC day to roll over, or the owner raises it
`signature_invalid`	400	false	you	The owner's signature does not match the terms (owner side)
`idempotency_key_reused`	409	false	you	This key was used for a different request. Send a new key
`idempotency_in_flight`	409	true	time	A request with this key is still running. Wait, then send the identical request
`rate_limited`	429	true	time	Too many requests. Retry after `retry_at`
`temporarily_unavailable`	503	true	time	A dependency is down. Retry shortly
`schema_not_applied`	503	true	operator	The tables for this feature are not created on this deployment yet

A rule break is not a refusal#

A rule break you report is stored, flagged and answered 202 with violation: true, violation_detail.codes and retry_safe: false. See Reporting events.

MCP#

MCP tools answer a refusal as {error: {reason, message, retry_safe}}.

Retrying#

retry_safe: true: wait (retry_at if present) and resend the identical request.
retry_safe: false: fix the cause named in who_fixes, then send a new request.
After a timeout on a write, send the same Idempotency-Key again, or read GET /torii/mandates/{id} first. Never retry a write without a key.