Handling Preflight Rejection

agents intermediate

How to design your agent prompts to gracefully handle POLICY_REJECTED errors.

When an agent violates its policy, the MCP server returns a structured ToolError. Your agent should be instructed on how to recover.

Prerequisites

Understanding of MCP ToolErrors

Using Preflight

Encourage the agent to use policy.preflight before large transfers. This avoids a hard rejection during the actual send.

{
  "agentId": "your-agent-id",
  "to": "0xTarget",
  "amount": "2000000"
}

Handling the Error

If transfer.send returns a POLICY_REJECTED error, the agent receives a suggestion field. For example, if draining a large balance to the owner, the suggestion will advise chunking the transfer.

{
  "ok": false,
  "error": {
    "code": "POLICY_REJECTED",
    "message": "Amount 2,000,000 OKRW exceeds spending limit 1,000,000 OKRW",
    "suggestion": "Reduce amount to 1,000,000 OKRW or less."
  }
}

Tip: Add a system prompt instruction: 'If a transfer is rejected due to spending limits, split the transfer into smaller chunks that fit within the limit.'

Conclusion

By handling structured errors, your agent can autonomously recover from policy blocks without human intervention.