Status & Errors

Alpha Ladder MCP tools are a thin proxy over the Alpha Ladder backend. A successful call returns the tool's payload; a failed call is surfaced to the AI client as a tool error. This page documents every response and error shape you can encounter and the recommended handling for each.

How errors reach the AI client

Understanding the mechanism first makes the rest of this page easier to handle correctly:

• Success — the tool returns its payload. Most AgentX tools wrap it in a standard success envelope (see below); a few return a bare value or array.
• Failure — when the backend returns a non-2xx HTTP status, the MCP layer does not return a normal payload. Instead the tool result is flagged as an error result (isError), and the error text is the backend's raw response body — usually a JSON string such as {"message":"Service temporarily unavailable"} or {"success":false,"code":"QUOTE_EXPIRED","message":"..."}.

Practical consequence for agents: when a tool call comes back as an error, read the error text — it carries the machine-readable code/message you need to decide what to do. Do not assume an error result is a transport failure to be blindly retried; most are deliberate business signals (expired quote, rate drift, validation failure) that retrying will not fix.

Success wrapper

Most AgentX tools wrap their payload in a standard success envelope:

{
  "success": true,
  "code": 200,
  "msg": "ok",
  "data": { ... }
}

When success is false, read msg (and code where present) to determine the cause. Do not attempt to parse data on a failure response.

For AgentX tool-specific response shapes, see AgentX — Response Reference.

Re-authentication error shape

When a session has expired, or the server cannot authenticate the request, tools return a distinct error object instead of the standard success wrapper:

{
  "error": true,
  "message": "Session expired",
  "authUrl": "https://www.alphaladder.hk/auth/..."
}

Handling:

1. Check whether the response has an error: true field before processing the success wrapper.
2. If authUrl is present, surface it to the user and prompt them to re-authenticate. Do not silently redirect automated agents.
3. After the user completes authentication, retry the original tool call.
4. If authUrl is absent, the error is likely a server-side configuration issue — do not auto-retry.

Transient service errors

When a backend step fails transiently — rather than rejecting the request on business grounds — the call is surfaced as a 503:

OTC quote & trade errors

The two-step OTC exchange flow has its own failure modes. They surface in two different ways depending on the step.

get_otc_quote — soft failures (Step 1)

get_otc_quote returns a normal response with success: false (it does not raise an HTTP error):

{ "success": false, "message": "Insufficient USD balance to exchange 100 USD for EUR." }

Typical causes are insufficient balance, an unsupported currency pair, or an amount above the maximum / below the minimum. Show message to the user, return them to currency selection, and do not auto-retry.

Additionally, if get_otc_quote succeeds but returns exchangeRate: "" or finalAmount: "", the downstream pricing service cannot price that pair at that moment. Do not proceed to confirm_otc_trade — inform the user and let them retry later or choose a different pair.

confirm_otc_trade — HTTP errors (Step 2)

confirm_otc_trade surfaces failures as HTTP-level errors, not as { "success": false } payloads. The server re-fetches a fresh quote at confirm time and trades at the live rate, so two conditions can reject the confirmation:

Critical: Do not auto-retry on 410 or 409. Both conditions require the user to explicitly review a new quote. Auto-retrying a destructive financial operation without user review is unsafe.

For the full OTC two-step workflow, see Exchange & OTC.

Validation errors

Requests with missing or malformed parameters are rejected before any business logic runs and surface as an HTTP 400 Bad Request tool error, with a message describing the offending field(s). Unknown/extra parameters are stripped rather than rejected.

These are caused by the AI client sending arguments that don't match a tool's schema. They are not retryable as-is — correct the arguments (consult the tool's parameter descriptions) and call again.

General error-handling guidance

• Never auto-retry destructive operations. This includes confirm_otc_trade and execute_fiat_withdrawal. If either of these returns an error, surface it to the user and wait for explicit confirmation before attempting a new request.
• Don't retry business errors. 410/409 OTC errors, 400 validation errors, and success: false soft failures are deliberate signals — retrying without changing something (a fresh quote, corrected arguments) will fail again.
• Retry only transient failures — e.g. 503, timeouts, or network errors on safe read operations such as get_deposit_list or get_account_summary — and only with exponential backoff. See Rate Limits for backoff guidance.
• Always surface the error message to the user. MCP tools run in AI client contexts. When a tool returns an error, present its message in plain language rather than silently retrying or swallowing the failure.

Cross-references

• AgentX — Response Reference — minor units, OTC trade codes, deposit/withdrawal status fields.
• Rate Limits — request cadence guidance and backoff posture.