Taxonomía de errores

Cuando una llamada al Gateway falla, recibes el error como una envoltura JSON uniforme:

{
  "error": {
    "code": "validation_error",
    "message": "Params violate the capability input schema.",
    "hint": "Call describe(id) and resend params matching input_schema.",
    "retryable": false,
    "audit_id": "audit_123"
  }
}

Códigos de error

Code	Significado para Agents
validation_error	La entrada no coincide con el esquema; leer describe y corregir
auth_required	Falta el Bearer-Key o no es válido
scope_missing	La Key no tiene el scope necesario
not_found / version_not_found	Verificar ID o versión
not_implemented	visible en el catálogo, pero no invocable
dry_run_required	primero enviar un dry_run exitoso con los mismos parámetros
precondition_failed	falta una precondición de negocio, no repetir a ciegas
conflict	El estado objetivo genera conflicto, leer nuevamente y decidir
rate_limited	respetar retry_after_seconds
budget_exceeded	aclarar Wallet, Budget o Policy
capability_disabled	Kill-Switch o bloqueo de Capability activo
approval_required / approval_rejected	se requiere Handover o decisión humana
upstream_error	un servicio externo/conectado no respondió correctamente
internal_error	reintentar más tarde; si se repite, proporcionar Audit-ID al soporte

Regla de reacción

retryable: true no significa «saturar inmediatamente». Reintenta con backoff, mismo Idempotency-Key y misma intención. Con retryable: false primero cambia la causa o deriva a una persona.

HTTP 412 en Onboarding

HTTP 412 precondition_failed en el flujo inicial es un comportamiento esperado cuando aún falta una precondición de negocio.

Endpoint	Cuándo se espera 412	Reacción
GET /org/current	antes del Owner-Claim o, si agent_email está configurado, antes de la verificación del correo del Agent	completar el paso OTP faltante, luego usar nuevamente como lectura de estado
POST /keys/rotate	antes del Owner-Claim o antes de la verificación requerida del correo del Agent	completar flujo inicial; no reemplazar una Key perdida mediante un nuevo Bootstrap
POST /mcp/dry_run	antes de OTPs requeridos o antes de Operator-Approval	hacer polling de /org/current hasta que operator_approval_status sea approved
POST /mcp/invoke	antes de OTPs requeridos o antes de Operator-Approval	no trabajar operativamente; aplicar regla de polling o Handover

Reacción: Espera el código del Owner, llama a POST /owner-otp/claim y si agent_email está configurado, verifica adicionalmente POST /agent-otp/verify. Luego repite /org/current como lectura de estado. Si operator_approval_status permanece pending durante mucho tiempo, sigue la Solución de problemas.

Continuar

Budgets & Kill-Switch