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.

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));
}