---
title: Errors
description: prepare_payment failure classes, JSON-RPC errors, and tool errors. Generated from code.
url: https://thepoints.io/docs/agents/reference/errors
audience: [agents, operators, developers]
---

# Errors

> **Agent Pay status:** Approve does not execute. Execution: not enabled. ACH settlement: not enabled. prepare_payment never moves money. Machine-readable: [/docs/agents/status.json](/docs/agents/status.json).

Generated from code. Machine-readable: [/docs/agents/reference/errors.json](/docs/agents/reference/errors.json).

## prepare_payment cash check codes (warning today, refusal at a future execution launch)

Prepare warns today through the optional `cash_check` result and the approval card. At a future execution launch, the same codes become refusals before a new reservation. Other refusals return a readable message that can change. A stored balance snapshot older than 24 hours is unknown by default. No payment is sent by prepare.

| Code | Meaning |
|---|---|
| `unreserved_cash_insufficient` | The proposed draft exceeds unreserved cash. |
| `unreserved_cash_unknown` | A recent available cash snapshot is required. |

## prepare_payment failure classes

When `prepare_payment` fails unexpectedly, the tool error text is `prepare_payment failed: <class>` with one of these classes.

| Class | Meaning |
|---|---|
| `database_unavailable` | POINTS could not reach its database. Retry later with the same idempotencyKey. |
| `payment_prepare_failed` | The draft could not be prepared, for example because the agent is unavailable. Nothing was created. |
| `invalid_tool_input` | The input was malformed, used a forbidden selector, or reused an idempotencyKey with different data. |
| `policy_blocked` | Agent policy or permissions block this payment. |
| `internal_tool_error` | An unexpected server error. Nothing was created. |

## JSON-RPC errors

| Code | Meaning |
|---|---|
| `-32601` | Unknown tool or method. |
| `-32602` | Invalid tool arguments. The error data names the field, never its value. |

## Tool errors

- Any tool: `Missing required scope: <scope>` when the grant lacks the tool's scope. Reconnect and approve the scope.
- `create_payment_draft`: every call returns `create_payment_draft is no longer an advertised POINTS MCP tool. Refresh tool discovery and use prepare_payment for Agent Pay payment preparation.`
- A revoked connection gets HTTP 401 on every call.