Errors

KleePay APIs return structured errors so agents can decide whether to retry, ask the user for action, or stop safely.

Cloud API shape

The frontdesk API client expects cloud API errors in this shape:

{
  "error": {
    "code": "string",
    "message": "Human-readable message"
  }
}

Local daemon checks

Start with GET /health when diagnosing a local integration:

curl -s http://127.0.0.1:7723/health

If /health fails, the issue is local daemon availability rather than a payment authorization failure.

Common classes

Class	Meaning	Agent behavior
Missing bearer token	The daemon endpoint requires Authorization: Bearer <token>.	Read ~/.kleepay/daemon_token and retry once.
Card not found	The selected card_id is unavailable or belongs to another account.	Call kleepay_list_cards and ask the user to choose another card.
Insufficient funds	Wallet or card balance is not enough for the requested operation.	Check kleepay_wallet_balance; ask the user before allocating or depositing funds.
Authorization expired	The scoped authorization TTL elapsed before the merchant charged.	Create a new authorization only if the user still wants the payment.
Scope mismatch	Merchant or amount does not match the authorization.	Do not widen scope automatically; ask the user for explicit approval.
Setup token expired	The dashboard install command expired before the device connected.	Regenerate the setup command in Devices and run setup again.
Local key not recognized	The local keystore unlocks, but server-backed commands fail because the server no longer recognizes the key.	Treat this as local/server key divergence; reconnect the device with fresh key material.
Upstream API unavailable	Server-backed commands return transient gateway or provider errors after local daemon health is OK.	Separate local daemon health from cloud/API health and retry only the affected server-backed operation.

Safety rule

Agents should not silently retry by widening merchant scope, raising amount limits, or extending TTL. Those changes create a different payment authorization and should be user-approved.