Error Reference

REST and MCP fail differently, and the difference matters when you write retry logic. REST returns an HTTP status with a JSON envelope; an MCP tool returns HTTP 200 with isError on the result.

// REST — GET/POST /api/v1/...
{
  "success": false,
  "error": "Human-readable message",
  "code": "MACHINE_CODE",   // present on some endpoints, not all
  "details": { ... }        // optional
}

// MCP tool result — transport status is 200
{
  "isError": true,
  "content": [{ "type": "text", "text": "Human-readable message" }],
  "structuredContent": {
    "error": {
      "code": "CART_NOT_MUTABLE",
      "remedy": "refresh_state",
      "retryable": false,
      "scope": "call",
      "details": { ... },
      "reference": "https://trusteed.xyz/en/developers/errors#CART_NOT_MUTABLE"
    }
  }
}

Returned when the API key is missing, invalid, or lacks the required permissions to perform the requested action.

Rate limits are enforced per key and per tool. Read the X-RateLimit-Reset header to know when the window resets.

Returned when a request is structurally valid but fails due to application state (e.g. cart expired, store not found).

When an MCP tool fails, the transport still returns 200. The failure is on the result. Branch on structuredContent.error.remedy: it is a closed set, so you can handle it exhaustively. Codes marked funds captured mean a charge may already exist; retrying one of those can charge the buyer twice. PAYMENT_OUTCOME_UNKNOWN is the other possible-charge code: the charge request reached the processor and nobody knows what it did, so the checkout is held: stop, do not retry with any key or payment method, and escalate.

Not all errors are worth retrying. Follow these rules to build resilient integrations.

// Exponential backoff: max 4 retries
const RETRYABLE = new Set([429, 500, 503]);

async function callWithRetry(fn: () => Promise<Response>): Promise<Response> {
  let attempt = 0;
  while (attempt <= 4) {
    const res = await fn();
    if (res.ok || !RETRYABLE.has(res.status)) return res;

    if (res.status === 429) {
      const reset = res.headers.get("X-RateLimit-Reset");
      const waitMs = reset ? (Number(reset) * 1000 - Date.now()) : 1000;
      await sleep(Math.max(waitMs, 0));
    } else {
      await sleep(1000 * 2 ** attempt); // 1s → 2s → 4s → 8s
    }
    attempt++;
  }
  return fn();
}

function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}