Error Codes

Standard JSON-RPC error codes plus AI Coach-specific extensions.

JSON-RPC standard

Code	Name	Meaning
-32700	Parse error	Body wasn't valid JSON.
-32600	Invalid request	Missing jsonrpc / method, or batch was empty.
-32601	Method not found	Unknown JSON-RPC method or unknown tool name.
-32602	Invalid params	Tool arguments failed schema validation. data.errors lists field-level reasons.
-32603	Internal error	Server-side exception. data.detail may carry the message.

AI Coach extensions

Code	Name	Meaning
-32001	Unauthorized	Tool requires auth and no key was supplied (or it's revoked / expired).
-32002	Forbidden	Key is valid but lacks the required scope, or the tool isn't on the key's allowlist.

payment_required content block

When a paid call exceeds free tier or the wallet/cap can't cover it, the tool returns isError: true and a structured content block with a top-up URL the agent should surface to the user.

{
  "isError": true,
  "content": [
    {
      "type": "resource",
      "resource": {
        "uri": "https://aicoach.pw/billing/checkout?return=mcp:abc123",
        "mimeType": "text/html"
      }
    },
    {
      "type": "text",
      "text": "Payment required: this call needs $0.40 in your wallet. Top up at the URL above and re-run."
    }
  ]
}

Agents that render resource blocks (Claude Code, Cursor, Zed) display the link inline. Other agents fall back to the text block. Either way, the user has enough information to top up and retry.