Modelo de Error

Asset Core utiliza códigos de estado HTTP estándar con respuestas de error de detalles del problema según la RFC 9457. Esta referencia describe el modelo de error y las condiciones de error comunes. Está diseñado para ser estable, de modo que los clientes puedan construir una lógica de reintento y remediación predecible.

Resumen

Los errores se devuelven como cargas útiles application/problem+json con una taxonomía estable, códigos legibles por máquina y orientación opcional para reintentos. El código de estado HTTP indica la categoría del error, mientras que el cuerpo proporciona detalles específicos. Trate el campo code como el identificador canónico legible por máquina.

Estructura

Respuesta de Error de Escritura/lectura (Detalles del Problema)

{
  "type": "urn:assetcore:error:CONTAINER_NOT_FOUND",
  "title": "NotFoundError",
  "status": 404,
  "detail": "Container 1001 not found",
  "code": "CONTAINER_NOT_FOUND",
  "retryable": false,
  "hint": "Verify the container ID",
  "server_correlation_id": "wr-0000000000000001-0000000000000042",
  "client_correlation_id": "client-req-2026-01-15",
  "details": {
    "container_id": 1001
  }
}

Campos de Detalle de Error

Campo	Tipo	Descripción
type	cadena	URI de tipo RFC 9457 (Asset Core utiliza urn:assetcore:error:\CODE“)
title	cadena	Nombre corto de la clase de error (ValidationError, NotFoundError)
status	entero	Código de estado HTTP
detail	cadena	Explicación legible por humanos
code	cadena	Identificador de error legible por máquina (SCREAMING_SNAKE_CASE)
retryable	booleano	Si los clientes deben reintentar
retry_after_ms	entero	Sugerencia opcional de reintento después en milisegundos (429/503)
hint	cadena	Sugerencia opcional de remediación
auth_reason	cadena	Razón opcional de denegación de autenticación (solo cuando la divulgación es reason_code)
server_correlation_id	cadena	ID de correlación asignado por el servidor opcional
client_correlation_id	cadena	ID de correlación proporcionado por el cliente opcional
details	objeto	Detalles estructurados opcionales
core_error	objeto	Carga útil de error central serializada opcional (solo para el daemon)

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 mal formado, campos faltantes
401 Unauthorized	No autenticado	Token de portador faltante o inválido
403 Forbidden	No permitido	El principal no tiene permiso o acceso al espacio de nombres
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
425 Too Early	Lectura obsoleta	Secuencia mínima del mundo no alcanzada (puntos finales de lectura)
429 Too Many Requests	Límite de tasa	Cuota o límites de tasa de autenticació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
CONTAINER_NOT_FOUND	404	El contenedor especificado no existe
CONTAINER_ALREADY_EXISTS	409	El ID del contenedor ya está en uso
WRONG_CONTAINER_KIND	422	Operación no soportada para este tipo de contenedor

Errores de Balance

Código	Estado	Descripción
INVALID_QUANTITY	422	La cantidad debe ser mayor que cero
INSUFFICIENT_BALANCE	422	Saldo insuficiente para la operación
INVALID_OPERATION	422	La operación provocaría un desbordamiento o es inválida

Errores de Instancia

Código	Estado	Descripción
INSTANCE_NOT_FOUND	404	La instancia especificada no existe
ALREADY_ATTACHED	409	La instancia ya tiene un padre
NOT_ATTACHED	422	La instancia no tiene un padre del cual desvincularse
HAS_CHILDREN	422	Debe desvincular a los hijos antes de eliminar
WOULD_CREATE_CYCLE	422	La vinculación crearía un ciclo

Errores de Slot

Código	Estado	Descripción
SLOT_OUT_OF_BOUNDS	422	El índice del slot excede la capacidad del contenedor
SLOT_OCCUPIED	409	El slot ya contiene una instancia
SLOT_EMPTY	422	El slot no contiene una instancia

Errores de Esquema

Código	Estado	Descripción
UNREGISTERED_CLASS	404	La clase especificada no está registrada
CLASS_ALREADY_EXISTS	409	El ID de clase ya está registrado
SHAPE_ALREADY_REGISTERED	409	La forma ya existe para esta clase
UNREGISTERED_CLASS_SHAPE	422	Se requiere forma pero no está registrada

Errores del Sistema

Código	Estado	Descripción
INVALID_REQUEST	400	JSON malformado o parámetros inválidos
PAYLOAD_TOO_LARGE	413	El cuerpo de la solicitud excede los límites configurados
UNSUPPORTED_MEDIA_TYPE	415	Content-Type no es JSON
INTEGER_OVERFLOW	500	Desbordamiento numérico (error)
SERVICE_UNAVAILABLE	503	El sistema está sobrecargado o en proceso de apagado

Ejemplos

Solicitud Incorrecta (400)

JSON inválido:

{
  "type": "urn:assetcore:error:INVALID_REQUEST",
  "title": "ValidationError",
  "status": 400,
  "detail": "Failed to parse JSON body",
  "code": "INVALID_REQUEST",
  "retryable": false,
  "details": {
    "position": 42,
    "expected": "string"
  }
}

No encontrado (404)

El contenedor no existe:

{
  "type": "urn:assetcore:error:CONTAINER_NOT_FOUND",
  "title": "NotFoundError",
  "status": 404,
  "detail": "Container 1001 does not exist",
  "code": "CONTAINER_NOT_FOUND",
  "retryable": false,
  "details": {
    "container_id": 1001
  }
}

Conflicto (409)

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

{
  "type": "urn:assetcore:error:IDEMPOTENCY_CONFLICT",
  "title": "ConflictError",
  "status": 409,
  "detail": "Idempotency key 'create-1001' was used with different request content",
  "code": "IDEMPOTENCY_CONFLICT",
  "retryable": false,
  "details": {
    "idempotency_key": "create-1001"
  }
}

Entidad No Procesable (422)

Saldo insuficiente:

{
  "type": "urn:assetcore:error:INSUFFICIENT_BALANCE",
  "title": "ValidationError",
  "status": 422,
  "detail": "Insufficient balance: requested 500, available 100",
  "code": "INSUFFICIENT_BALANCE",
  "retryable": false,
  "details": {
    "container_id": 1001,
    "class_id": 100,
    "key": 1,
    "requested": 500,
    "available": 100
  }
}

Servicio No Disponible (503)

Sistema sobrecargado:

{
  "type": "urn:assetcore:error:SERVICE_UNAVAILABLE",
  "title": "UnavailableError",
  "status": 503,
  "detail": "System is at capacity, please retry later",
  "code": "SERVICE_UNAVAILABLE",
  "retryable": true,
  "retry_after_ms": 100,
  "details": {
    "queue_depth": 1000
  }
}

Referencias relacionadas

• API HTTP - Referencia de endpoints
• Transacciones - Estructura de la solicitud
• Referencia de Acción - Errores específicos de operación