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": "150"
}

Handling the Error

If transfer.send returns a POLICY_REJECTED error, the agent receives detail.reason and a suggestion field. detail.reason names the rule it broke, and suggestion points to policy.get and policy.set. To return a balance larger than the limit to the owner, use agent.drain, which splits the balance into transfers no larger than the limit.

{
  "ok": false,
  "error": {
    "code": "POLICY_REJECTED",
    "message": "Policy rejected: Amount 150 OKRW exceeds spending limit 100 OKRW",
    "detail": {
      "agentId": "your-agent-id",
      "to": "0xTarget",
      "amount": "150",
      "reason": "Amount 150 OKRW exceeds spending limit 100 OKRW"
    },
    "suggestion": "Call `policy.get` to see the current rules, then `policy.set` to adjust `spendingLimit` or `allowedTargets`.",
    "retryable": false
  }
}

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.