Referencia API

Referencia de Errores

Catálogo completo de errores de la API v1 y MCP Gateway de Trusteed. Úsalo para escribir retry logic preciso y gestionar fallos de forma elegante.

Formato de Respuesta de Error

Todos los errores siguen un sobre JSON consistente. Parsea el campo error para identificar el tipo de error de forma programática.

{
  "error": "error_code",
  "message": "Mensaje legible por humanos",
  "details": { ... }
}

El campo error es estable entre versiones de API — construye la retry logic sobre él, no sobre el string message.

Errores de Autenticación

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

Código HTTP	Error	Significado	Acción Recomendada
401	`unauthorized`	API key ausente o inválida	Verifica que el header X-Agent-Api-Key esté presente y con formato correcto (agnt_xxx)
401	`token_expired`	El token OAuth ha expirado	Refresca el token con POST /api/v1/oauth/token
403	`forbidden`	La clave carece del scope necesario para esta acción	Revisa los scopes de la clave en el Dashboard bajo Agent Keys
403	`tier_required`	La funcionalidad requiere un plan superior	Actualiza el plan desde el Dashboard
403	`store_suspended`	El trust_score del merchant está por debajo de 0.20	Elige un merchant diferente — solo procede con trust_score ≥ 0.70

Errores de Rate Limit

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

Código HTTP	Error	Significado	Acción Recomendada
429	`rate_limit_exceeded`	Límite de peticiones por clave alcanzado	Pausa y reintenta tras el timestamp Unix en X-RateLimit-Reset
429	`tool_limit_exceeded`	Límite por herramienta superado (p.ej. search_products: 20/min)	Reduce la frecuencia de búsqueda o agrupa las peticiones

Headers de respuesta de rate limit

X-RateLimit-LimitMáximo de peticiones permitidas en la ventana actual
X-RateLimit-RemainingPeticiones restantes antes de alcanzar el límite
X-RateLimit-ResetTimestamp Unix (segundos) en que se renueva la ventana

Errores de Lógica de Negocio

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).

Código HTTP	Error	Significado	Acción Recomendada	Reintentable
400	`invalid_slug`	El formato del slug de tienda es inválido	Usa solo caracteres alfanuméricos y guiones (p.ej. mi-tienda)	No
404	`store_not_found`	La tienda no existe o está inactiva	Verifica el slug en el directorio de merchants	No
404	`product_not_found`	El producto no está disponible o ha sido retirado	Llama a search_products de nuevo para obtener una lista actualizada	No
409	`cart_expired`	El carrito tiene más de 30 minutos	Crea un nuevo carrito con create_cart	No
422	`checkout_not_ready`	El carrito está vacío o faltan campos requeridos	Añade artículos antes de llamar a complete_checkout	No
500	`internal_error`	Error de servidor inesperado	Reintenta con backoff exponencial (ver Guía de Reintentos abajo)	Sí
503	`service_unavailable`	Sobrecarga temporal o mantenimiento	Reintenta después de 30 segundos	Sí

Guía de Reintentos

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

Errores reintentables

429, 500, 503

Backoff: 1s → 2s → 4s → 8s (máx. 4 reintentos)

Errores no reintentables

400, 401, 403, 404, 409, 422

Corrige la petición antes de reintentar

Estrategia de backoff recomendada

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

Recursos relacionados

Documentación API

Autenticación, herramientas MCP y webhooks

Para agentes IA

Trust scores, rate limits y contratos MCP

Estado del sistema

Estado operativo en tiempo real

Volver a la Documentación

Explora autenticación, herramientas MCP, webhooks y más.

Documentación para Desarrolladores