Documentation Index
Fetch the complete documentation index at: https://docs.payo.dev/llms.txt
Use this file to discover all available pages before exploring further.
PaymentError
All payment-related errors are instances of PaymentError:
class PaymentError extends Error {
code: PaymentErrorCode;
details?: Record<string, unknown>;
}
Properties
| Property | Type | Description |
|---|
message | string | Human-readable error message |
code | PaymentErrorCode | Machine-readable error code |
details | object | Additional context (optional) |
Usage
import { PaymentError, PaymentErrorCode } from '@payo/mcp';
try {
// Tool call that might fail
} catch (error) {
if (error instanceof PaymentError) {
switch (error.code) {
case PaymentErrorCode.INSUFFICIENT_BALANCE:
console.log('Agent needs more credits');
break;
case PaymentErrorCode.TOKEN_INVALID:
console.log('Agent token is invalid');
break;
}
}
}
Error Codes
enum PaymentErrorCode {
TOKEN_MISSING = 'TOKEN_MISSING',
TOKEN_INVALID = 'TOKEN_INVALID',
INSUFFICIENT_BALANCE = 'INSUFFICIENT_BALANCE',
PLATFORM_UNAVAILABLE = 'PLATFORM_UNAVAILABLE',
CHARGE_FAILED = 'CHARGE_FAILED',
}
TOKEN_MISSING
Meaning: The agent didn’t provide a token.
When: Agent calls a paid tool without Authorization header or AGENT_TOKEN env var.
User Message (detailed):
Payment required. [Provider] has enabled Payo micropayments for '[tool]' ($X.XX).
To use this tool:
1. Get your agent token at https://payo.dev/agent/api-keys
2. Add the token to your MCP client's Authorization header
3. Documentation: https://docs.payo.dev/quickstart-agent
Questions? Contact cheng@payo.dev
TOKEN_INVALID
Meaning: The token exists but is invalid.
When:
- Token was deleted from dashboard
- Token is malformed
- Token doesn’t exist
User Message:
Invalid or expired agent token. Get a new one at https://payo.dev/agent/api-keys
INSUFFICIENT_BALANCE
Meaning: Agent doesn’t have enough credits.
When: Agent’s credits_balance is less than the tool’s price.
User Message (detailed):
Insufficient balance for '[tool]' (requires $X.XX, current balance: $Y.YY).
To add funds:
1. Visit https://payo.dev/agent/wallet
2. Top up your account balance
Documentation: https://docs.payo.dev/guides/agent/deposits
{
required: 0.05, // Price of the tool
available: 0.02, // Agent's current balance
tool: 'get_weather'
}
Meaning: Payo platform couldn’t be reached.
When:
- Network error
- Payo is down
- Request timeout
User Message:
Payment service temporarily unavailable. Please try again shortly.
Status: https://status.payo.dev
- With
failOpen: false (default): Tool fails
- With
failOpen: true: Tool executes without charging
Resolution: Retry later or wait for Payo status update.
CHARGE_FAILED
Meaning: Charge was rejected for another reason.
When:
- Provider API key is invalid
- Server-side validation error
- Unexpected platform error
User Message:
Payment processing failed. Please try again or contact support.
Error Flow
Agent calls paid tool
│
▼
Extract token ─────────────────────┐
│ │
│ No token │
▼ │
TOKEN_MISSING ◄────────────────────┘
│
│ Has token
▼
Call /api/v1/charge
│
┌────┴────┬─────────┬──────────────┐
│ │ │ │
▼ ▼ ▼ ▼
Success Invalid Balance Network
Token Too Low Error
│ │ │ │
│ ▼ ▼ ▼
│ TOKEN_INVALID INSUFFICIENT PLATFORM_
│ _BALANCE UNAVAILABLE
│
▼
Execute tool
│
▼
Return result
Handling Errors in Agents
Agents receive errors as tool call failures. The error message tells them what to do:
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32603,
"message": "Payment required for 'get_weather' ($0.01). Get your token at https://payo.dev/agent/api-keys"
}
}
- Parse the error message
- Show it to the user or log it
- Not retry immediately (except for
PLATFORM_UNAVAILABLE)
Logging Errors
Enable logging to see error details:
import { LogLevel } from '@payo/mcp';
const paidServer = withPayments(server, {
apiKey: process.env.PAYO_API_KEY!,
pricing: { 'my_tool': 0.01 },
logLevel: LogLevel.DEBUG,
});
[2024-01-15T10:30:45Z] [payo:info] Charge failed {
"code": "INSUFFICIENT_BALANCE",
"tool": "get_weather",
"agentToken": "sk_l****xyz9",
"required": 0.01
}
