Error codes

All errors follow this format:

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Payment of €80 exceeds available balance of €42.50",
    "details": {
      "requested": 80.00,
      "available": 42.50
    }
  }
}

Common error codes

Code	HTTP	Description
INSUFFICIENT_BALANCE	422	Payment amount exceeds available wallet balance
ACCOUNT_NOT_FOUND	404	The specified account code does not exist
INVALID_RECIPIENT	422	The payment destination is not a valid EURD account
AMOUNT_TOO_LOW	422	Amount is below the minimum for this operation
AMOUNT_TOO_HIGH	422	Amount exceeds your profile limit
PAYMENT_REQUEST_EXPIRED	422	The payment request has passed its expiry date
PAYMENT_REQUEST_PAID	422	This one-off payment request has already been paid
KYC_REQUIRED	403	Operation requires a higher KYC tier
SCOPE_REQUIRED	403	API key lacks the required scope (e.g. BusinessPremium)
DUPLICATE_IDEMPOTENCY_KEY	200	Request already processed — original result returned
ACCOUNT_BALANCE_NOT_ZERO	422	Cannot delete account with non-zero balance
OTP_EXPIRED	422	The OTP has expired (valid for 2 minutes)
RATE_LIMIT_EXCEEDED	429	Too many requests — back off and retry
INTERNAL_ERROR	500	Unexpected server error — contact support

Handling errors in agents

LLMs read the message field to give users actionable feedback. The details object provides structured data for conditional logic.

// Example: handle insufficient balance gracefully
if (error.code === "INSUFFICIENT_BALANCE") {
  const needed = error.details.requested - error.details.available;
  return `You need €${needed.toFixed(2)} more in your wallet.
          Would you like to top up via iDEAL?`;
}

Idempotency

If you send a request with an Idempotency-Key that was already processed within 24 hours, the server returns the original result with HTTP 200 — not an error. Check for "dry_run": true in the response if you used dry-run mode.