Error Model

Asset Core utilitza codis d’estat HTTP estàndard amb respostes d’error de detalls del problema RFC 9457. Aquesta referència descriu el model d’error i les condicions d’error comunes. Està dissenyada per ser estable perquè els clients puguin construir una lògica de reintents i remediació previsible.

Visió general

Els errors es retornen com a càrregues application/problem+json amb una taxonomia estable, codis llegibles per màquina i orientació opcional per a reintents. El codi d’estat HTTP indica la categoria d’error, mentre que el cos proporciona detalls específics. Tracteu el camp code com l’identificador canònic llegible per màquina.

Estructura

Resposta d’Error de Lectura/Escriptura (Detalls 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
  }
}

Camps de Detall d’Error

Camp	Tipus	Descripció
type	cadena	URI de tipus RFC 9457 (Asset Core utilitza urn:assetcore:error:\CODE“)
title	cadena	Nom curt de la classe d’error (ValidationError, NotFoundError)
status	enter	Codi d’estat HTTP
detail	cadena	Explicació llegible per humans
code	cadena	Identificador d’error llegible per màquina (SCREAMING_SNAKE_CASE)
retryable	booleà	Si els clients han de tornar a intentar
retry_after_ms	enter	Suggeriment opcional de tornar a intentar després en mil·lisegons (429/503)
hint	cadena	Suggeriment opcional de remediació
auth_reason	cadena	Motiu opcional de denegació d’autenticació (només quan la divulgació és reason_code)
server_correlation_id	cadena	ID de correlació assignat pel servidor opcional
client_correlation_id	cadena	ID de correlació proporcionat pel client opcional
details	objecte	Detalls estructurats opcionals
core_error	objecte	Càrrega d’error central serialitzada opcional (només per al daemon d’escriptura)

Campanyes

Codi d’estat HTTP

Estat	Significat	Quan s’utilitza
200 OK	Èxit	Sol·licitud completada amb èxit
400 Bad Request	Sol·licitud invàlida	JSON malformat, camps mancants
401 Unauthorized	No autenticat	Token de portador mancant o invàlid
403 Forbidden	No permès	El principal no té permís o accés a l’espai de noms
404 Not Found	Recurso no trobat	El contenidor o la classe no existeix
409 Conflict	Conflicte d’estat	Col·lisió de la clau d’idempotència, ja existeix
422 Unprocessable Entity	Validació fallida	Condicions prèvies de l’operació no complertes
425 Too Early	Lectura obsoleta	Seqüència mínima del món no assolida (punts finals de lectura)
429 Too Many Requests	Limitat per taxa	Quota o límits de taxa d’autenticació
500 Internal Server Error	Error del servidor	Fallades inesperades
503 Service Unavailable	Temporalment no disponible	Sobrecàrrega, apagant-se

Codi d’Error Comú

Errors de contenidor

Codi	Estat	Descripció
CONTAINER_NOT_FOUND	404	El contenidor especificat no existeix
CONTAINER_ALREADY_EXISTS	409	L’ID del contenidor ja està en ús
WRONG_CONTAINER_KIND	422	Operació no suportada per aquest tipus de contenidor

Errors de Balance

Codi	Estat	Descripció
INVALID_QUANTITY	422	La quantitat ha de ser superior a zero
INSUFFICIENT_BALANCE	422	No hi ha prou saldo per a l’operació
INVALID_OPERATION	422	L’operació causaria un desbordament o és invàlida

Errors d’Instància

Codi	Estat	Descripció
INSTANCE_NOT_FOUND	404	La instància especificada no existeix
ALREADY_ATTACHED	409	La instància ja té un pare
NOT_ATTACHED	422	La instància no té cap pare del qual desconnectar-se
HAS_CHILDREN	422	Cal desconnectar els fills abans de cremar
WOULD_CREATE_CYCLE	422	L’adjunció crearia un cicle

Errors de Slot

Codi	Estat	Descripció
SLOT_OUT_OF_BOUNDS	422	L’índex del slot excedeix la capacitat del contenidor
SLOT_OCCUPIED	409	El slot ja conté una instància
SLOT_EMPTY	422	El slot no conté cap instància

Errors d’Esquema

Codi	Estat	Descripció
UNREGISTERED_CLASS	404	La classe especificada no està registrada
CLASS_ALREADY_EXISTS	409	L’ID de classe ja està registrat
SHAPE_ALREADY_REGISTERED	409	La forma ja existeix per a aquesta classe
UNREGISTERED_CLASS_SHAPE	422	Forma requerida però no registrada

Errors del sistema

Codi	Estat	Descripció
INVALID_REQUEST	400	JSON malformat o paràmetres invàlids
PAYLOAD_TOO_LARGE	413	El cos de la sol·licitud supera els límits configurats
UNSUPPORTED_MEDIA_TYPE	415	Content-Type no és JSON
INTEGER_OVERFLOW	500	Desbordament numèric (error)
SERVICE_UNAVAILABLE	503	El sistema està sobrecarregat o s’està apagant

Exemples

Sol·licitud incorrecta (400)

JSON invàlid:

{
  "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 Trobat (404)

El contenidor no existeix:

{
  "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
  }
}

Conflicte (409)

La clau d’idempotència ja s’ha utilitzat amb contingut diferent:

{
  "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"
  }
}

Entitat No Processable (422)

Saldo insuficient:

{
  "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
  }
}

Servei No Disponible (503)

Sistema sobrecarregat:

{
  "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
  }
}

Referències relacionades

• HTTP API - Referència d’endpoint
• Transaccions - Estructura de la sol·licitud
• Referència d’Acció - Errors específics de l’operació