Referencia de Errores

REST y MCP fallan de forma distinta, y la diferencia importa al escribir la lógica de reintentos. REST devuelve un código HTTP con un sobre JSON; una herramienta MCP devuelve HTTP 200 con isError dentro del resultado.

// REST — GET/POST /api/v1/...
{
  "success": false,
  "error": "Mensaje legible por humanos",
  "code": "MACHINE_CODE",   // presente en algunos endpoints, no en todos
  "details": { ... }        // opcional
}

// Resultado de herramienta MCP — el estado del transporte es 200
{
  "isError": true,
  "content": [{ "type": "text", "text": "Mensaje legible por humanos" }],
  "structuredContent": {
    "error": {
      "code": "CART_NOT_MUTABLE",
      "remedy": "refresh_state",
      "retryable": false,
      "scope": "call",
      "details": { ... },
      "reference": "https://trusteed.xyz/es/developers/errors#CART_NOT_MUTABLE"
    }
  }
}

Se devuelven cuando falta la API key, es inválida o carece de los permisos necesarios para realizar la acción solicitada.

Los rate limits se aplican por clave y por herramienta. Lee el header X-RateLimit-Reset para saber cuándo se renueva la ventana.

Se devuelven cuando una petición es estructuralmente válida pero falla por el estado de la aplicación (p.ej. carrito expirado, tienda no encontrada).

Cuando una herramienta MCP falla, el transporte sigue devolviendo 200. El fallo va en el resultado. Decide por structuredContent.error.remedy: es un conjunto cerrado, así que puedes cubrirlo por completo. Los códigos marcados como fondos capturados significan que puede existir ya un cargo; reintentar uno de ésos puede cobrar dos veces al comprador. PAYMENT_OUTCOME_UNKNOWN es el otro código con posible cargo: la petición de cobro llegó al procesador y no se sabe qué hizo, así que el checkout queda retenido: para, no reintentes con ninguna clave ni método de pago, y escala.

No todos los errores vale la pena reintentar. Sigue estas reglas para construir integraciones resilientes.

// Backoff exponencial: máximo 4 reintentos
const REINTENTABLES = new Set([429, 500, 503]);

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

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

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