Modelo de Error

Asset Core utiliza códigos de estado HTTP estándar con respuestas de error JSON estructuradas. Esta referencia describe el modelo de error y las condiciones de error comunes.

Visión general

Los errores se devuelven como objetos JSON con detalles sobre qué falló y por qué. El código de estado HTTP indica la categoría del error, mientras que el cuerpo proporciona especificaciones.

Estructura

Respuesta de Error

{
  "error": {
    "code": "ErrorCode",
    "message": "Human-readable description",
    "details": {
      "field": "additional context"
    }
  }
}

Campos de Detalle de Error

Campo	Tipo	Descripción
`code`	cadena	Identificador de error legible por máquina
`message`	cadena	Descripción legible por humanos
`details`	objeto	Contexto adicional (varía según el error)
`operation_index`	entero	Qué operación falló (para transacciones)

Campos

Códigos de Estado HTTP

Estado	Significado	Cuándo se utiliza
`200 OK`	Éxito	Solicitud completada con éxito
`400 Bad Request`	Solicitud inválida	JSON malformado, campos faltantes
`404 Not Found`	Recurso no encontrado	El contenedor o clase no existe
`409 Conflict`	Conflicto de estado	Colisión de clave de idempotencia, ya existe
`422 Unprocessable Entity`	Validación fallida	No se cumplieron las condiciones previas de la operación
`500 Internal Server Error`	Error del servidor	Fallos inesperados
`503 Service Unavailable`	Temporalmente no disponible	Sobrecargado, apagándose

Códigos de Error Comunes

Errores de Contenedor

Código	Estado	Descripción
`ContainerNotFound`	404	El contenedor especificado no existe
`ContainerAlreadyExists`	409	El ID del contenedor ya está en uso
`WrongContainerKind`	422	Operación no soportada para este tipo de contenedor

Errores de Balance

Código	Estado	Descripción
`InvalidQuantity`	422	La cantidad debe ser mayor que cero
`InsufficientBalance`	422	No hay suficiente saldo para la operación
`InvalidOperation`	422	La operación causaría un desbordamiento o es inválida

Errores de Instancia

Código	Estado	Descripción
`InstanceNotFound`	404	La instancia especificada no existe
`AlreadyAttached`	409	La instancia ya tiene un padre
`NotAttached`	422	La instancia no tiene un padre del cual desasociarse
`HasChildren`	422	Debe desasociar a los hijos antes de quemar
`WouldCreateCycle`	422	La asociación crearía un ciclo

Errores de Slot

Código	Estado	Descripción
`SlotOutOfBounds`	422	El índice del slot excede la capacidad del contenedor
`SlotOccupied`	409	El slot ya contiene una instancia
`SlotEmpty`	422	El slot no contiene una instancia

Errores de Esquema

Código	Estado	Descripción
`ClassNotFound`	404	La clase especificada no está registrada
`ClassAlreadyExists`	409	El ID de clase ya está registrado
`ShapeAlreadyDefined`	409	El ID de forma ya existe para esta clase
`UnregisteredClassShape`	422	Se requiere forma pero no está registrada

Errores del Sistema

Código	Estado	Descripción
`ParseError`	400	JSON inválido en el cuerpo de la solicitud
`ValidationError`	422	La validación de la solicitud falló
`IntegerOverflow`	422	La operación numérica provocaría un desbordamiento
`ServiceUnavailable`	503	El sistema está sobrecargado o en proceso de apagado

Ejemplos

Solicitud Incorrecta (400)

JSON inválido:

{
  "error": {
    "code": "ParseError",
    "message": "Failed to parse JSON body",
    "details": {
      "position": 42,
      "expected": "string"
    }
  }
}

No encontrado (404)

El contenedor no existe:

{
  "error": {
    "code": "ContainerNotFound",
    "message": "Container 1001 does not exist",
    "details": {
      "container_id": 1001
    }
  }
}

Conflicto (409)

La clave de idempotencia ya se utilizó con contenido diferente:

{
  "error": {
    "code": "IdempotencyConflict",
    "message": "Idempotency key 'create-1001' was used with different request content",
    "details": {
      "idempotency_key": "create-1001"
    }
  }
}

Entidad No Procesable (422)

Saldo insuficiente:

{
  "error": {
    "code": "InsufficientBalance",
    "message": "Insufficient balance: requested 500, available 100",
    "details": {
      "container_id": 1001,
      "class_id": 100,
      "key": 1,
      "requested": 500,
      "available": 100
    },
    "operation_index": 0
  }
}

Servicio No Disponible (503)

Sistema sobrecargado:

{
  "error": {
    "code": "ServiceUnavailable",
    "message": "System is at capacity, please retry later",
    "details": {
      "queue_depth": 1000,
      "retry_after_ms": 100
    }
  }
}

Referencias relacionadas

API HTTP - Referencia de endpoints
Transacciones - Estructura de la solicitud
Operaciones por Dominio - Errores específicos de operación