Model d’Error

Asset Core utilitza codis d’estat HTTP estàndard amb respostes d’error JSON estructurades. Aquesta referència descriu el model d’error i les condicions d’error comunes.

Visió general

Els errors es retornen com a objectes JSON amb detalls sobre què ha fallat i per què. El codi d’estat HTTP indica la categoria d’error, mentre que el cos proporciona especificacions.

Estructura

Resposta d’Error

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

Camps de Detall d’Error

Camp	Tipus	Descripció
`code`	cadena	Identificador d’error llegible per màquina
`message`	cadena	Descripció llegible per humans
`details`	objecte	Context addicional (varia segons l’error)
`operation_index`	enter	Quina operació ha fallat (per a transaccions)

Camps

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 mancant
`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
`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ó
`ContainerNotFound`	404	El contenidor especificat no existeix
`ContainerAlreadyExists`	409	L’ID del contenidor ja està en ús
`WrongContainerKind`	422	Operació no suportada per aquest tipus de contenidor

Errors de Balance

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

Errors d’Instància

Codi	Estat	Descripció
`InstanceNotFound`	404	La instància especificada no existeix
`AlreadyAttached`	409	La instància ja té un pare
`NotAttached`	422	La instància no té cap pare del qual desconnectar-se
`HasChildren`	422	Cal desconnectar els fills abans de cremar
`WouldCreateCycle`	422	L’adjunció crearia un cicle

Errors de Slot

Codi	Estat	Descripció
`SlotOutOfBounds`	422	L’índex del slot excedeix la capacitat del contenidor
`SlotOccupied`	409	El slot ja conté una instància
`SlotEmpty`	422	El slot no conté cap instància

Errors d’Esquema

Codi	Estat	Descripció
`ClassNotFound`	404	La classe especificada no està registrada
`ClassAlreadyExists`	409	L’ID de classe ja està registrat
`ShapeAlreadyDefined`	409	L’ID de forma ja existeix per a aquesta classe
`UnregisteredClassShape`	422	Es requereix una forma però no està registrada

Errors del sistema

Codi	Estat	Descripció
`ParseError`	400	JSON no vàlid al cos de la sol·licitud
`ValidationError`	422	La validació de la sol·licitud ha fallat
`IntegerOverflow`	422	L’operació numèrica provocaria un desbordament
`ServiceUnavailable`	503	El sistema està sobrecarregat o s’està apagant

Exemples

Sol·licitud incorrecta (400)

JSON invàlid:

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

No Trobat (404)

El contenidor no existeix:

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

Conflicte (409)

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

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

Entitat No Processable (422)

Saldo insuficient:

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

Servei No Disponible (503)

Sistema sobrecarregat:

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

Referències relacionades

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