Error Reference

All error responses from the Payments for AI Agents API share a common shape:

{
  "status": "error",
  "errorCode": "ERROR_CODE_HERE",
  "error": "Human-readable description"
}

Field	Type	Description
status	"error"	Always "error" for error responses
errorCode	string	Machine-readable code — use this for programmatic handling
error	string	Human-readable description — suitable for user-facing messages

Error codes

AI_AUTHORIZATION_INVALID

HTTP status	Endpoint	Trigger
401	All	Authorization header is missing
403	All	Token value is invalid, revoked, or agent access is disabled in the dashboard

Recovery:

• On 401: add the Authorization: Bearer <token> header to the request.
• On 403: verify the token value is correct. If the token was revoked, get a new agent instruction for the card and update the agent configuration.

The agent can retry after fixing the token. Do not retry without fixing the token — the same error will recur.

AI_TOPUP_INSUFFICIENT_BALANCE

HTTP status	Endpoint
500	POST /topup-request

The user's Holyheld main account does not have enough available balance to cover the requested top-up amount.

Recovery: This error cannot be resolved by the agent. The user must add funds to their Holyheld account before another top-up can succeed. Notify the user with a clear, actionable message:

"I was unable to top up your Holyheld card. Your Holyheld account does not have enough available balance. Please add funds and try again."

Do not retry automatically — the error will persist until the user takes action.

AI_TOPUP_LIMIT_EXCEEDED

HTTP status	Endpoint
500	POST /topup-request

The agent's cumulative spending limit has been reached. This limit is set by the user in the Holyheld dashboard for the card's agent access.

Recovery: Only the user can reset this limit from the dashboard. Notify the user immediately:

"Your Holyheld agent spending limit has been reached. To allow further top-ups, please reset the limit in your Holyheld dashboard under Settings → Agentic access."

Do not retry. Further requests will continue to fail with the same error until the user resets the limit. If the agent is on a polling or scheduled loop, suspend top-up attempts for the current session after receiving this error.

WRONG_REQUEST

HTTP status	Endpoint
400	POST /topup-request

The request body was malformed or could not be parsed. The most common cause is an invalid amount value.

Recovery: Fix the amount field before retrying. The amount must:

• Be a string (not a number)
• Match the pattern ^\d+(\.\d{1,2})?$
• Contain no currency symbols, spaces, or negative signs

// ❌ Wrong
{ amount: 50 }           // number, not string
{ amount: "€50.00" }     // currency symbol
{ amount: "50.123" }     // more than 2 decimal places

// ✅ Correct
{ amount: "50.00" }
{ amount: (50).toFixed(2) }  // "50.00"

INTERNAL_SERVER_ERROR

HTTP status	Endpoint
500	All

An unexpected server-side error occurred.

Recovery: Retry with exponential backoff. If the error persists after several attempts, treat it as a temporary outage and surface a generic error to the user.

async function fetchWithRetry(url, options, maxAttempts = 3) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const res = await fetch(url, options);
    if (res.status !== 500) return res;

    const delay = 1000 * Math.pow(2, attempt); // 1s, 2s, 4s
    await new Promise((resolve) => setTimeout(resolve, delay));
  }
  throw new Error('Service temporarily unavailable. Please try again later.');
}

Recovery summary

Error code	Agent can fix?	Action
AI_AUTHORIZATION_INVALID (401)	✅ Yes	Add the Authorization header
AI_AUTHORIZATION_INVALID (403)	✅ Yes	Check the Bearer token or get new agent instructions
WRONG_REQUEST	✅ Yes	Fix the amount format and retry immediately
INTERNAL_SERVER_ERROR	✅ Partial	Retry with exponential backoff
AI_TOPUP_INSUFFICIENT_BALANCE	❌ No	Notify user — they must add funds to their account
AI_TOPUP_LIMIT_EXCEEDED	❌ No	Notify user — they must reset the limit in the dashboard

TypeScript error handling

type AgentErrorCode =
  | 'AI_AUTHORIZATION_INVALID'
  | 'AI_TOPUP_INSUFFICIENT_BALANCE'
  | 'AI_TOPUP_LIMIT_EXCEEDED'
  | 'WRONG_REQUEST'
  | 'INTERNAL_SERVER_ERROR';

interface AgentErrorResponse {
  status: 'error';
  errorCode: AgentErrorCode;
  error: string;
}

async function handleTopUp(amount: string, token: string): Promise<void> {
  const res = await fetch('https://apicore.holyheld.com/v4/ai-agents/topup-request', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ amount }),
  });

  if (res.ok) return; // 200 — accepted, proceed to polling

  const err: AgentErrorResponse = await res.json();

  switch (err.errorCode) {
    case 'AI_TOPUP_INSUFFICIENT_BALANCE':
      // Cannot fix — escalate to user
      throw new UserActionRequiredError(
        'Insufficient funds in your Holyheld account. Please add funds and try again.'
      );

    case 'AI_TOPUP_LIMIT_EXCEEDED':
      // Cannot fix — escalate to user, suspend further attempts
      throw new UserActionRequiredError(
        'Agent spending limit reached. Please reset the limit in your Holyheld dashboard.'
      );

    case 'WRONG_REQUEST':
      // Fix the amount and retry
      throw new Error(`Invalid amount format: ${amount}. Use toFixed(2).`);

    case 'AI_AUTHORIZATION_INVALID':
      throw new Error('Bearer token invalid or missing. Check your HOLYHELD_AGENT_TOKEN.');

    case 'INTERNAL_SERVER_ERROR':
    default:
      throw new Error(`Server error (${err.errorCode}): ${err.error}`);
  }
}

class UserActionRequiredError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'UserActionRequiredError';
  }
}

Next steps

See Build an MCP Server to wire up these error-handling patterns as Claude tools.