Error Model

Asset Core uses standard HTTP status codes with structured JSON error responses. This reference describes the error model and common error conditions.

Overview

Errors are returned as JSON objects with details about what failed and why. The HTTP status code indicates the error category, while the body provides specifics.

Structure

Error Response

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

Error Detail Fields

Field	Type	Description
`code`	string	Machine-readable error identifier
`message`	string	Human-readable description
`details`	object	Additional context (varies by error)
`operation_index`	integer	Which operation failed (for transactions)

Fields

HTTP Status Codes

Status	Meaning	When Used
`200 OK`	Success	Request completed successfully
`400 Bad Request`	Invalid request	Malformed JSON, missing fields
`404 Not Found`	Resource not found	Container or class doesn’t exist
`409 Conflict`	State conflict	Idempotency key collision, already exists
`422 Unprocessable Entity`	Validation failed	Operation preconditions not met
`500 Internal Server Error`	Server error	Unexpected failures
`503 Service Unavailable`	Temporarily unavailable	Overloaded, shutting down

Common Error Codes

Container Errors

Code	Status	Description
`ContainerNotFound`	404	The specified container doesn’t exist
`ContainerAlreadyExists`	409	Container ID is already in use
`WrongContainerKind`	422	Operation not supported for this container kind

Balance Errors

Code	Status	Description
`InvalidQuantity`	422	Quantity must be greater than zero
`InsufficientBalance`	422	Not enough balance for the operation
`InvalidOperation`	422	Operation would overflow or is invalid

Instance Errors

Code	Status	Description
`InstanceNotFound`	404	The specified instance doesn’t exist
`AlreadyAttached`	409	Instance already has a parent
`NotAttached`	422	Instance has no parent to detach from
`HasChildren`	422	Must detach children before burning
`WouldCreateCycle`	422	Attachment would create a cycle

Slot Errors

Code	Status	Description
`SlotOutOfBounds`	422	Slot index exceeds container capacity
`SlotOccupied`	409	Slot already contains an instance
`SlotEmpty`	422	Slot doesn’t contain an instance

Schema Errors

Code	Status	Description
`ClassNotFound`	404	The specified class isn’t registered
`ClassAlreadyExists`	409	Class ID is already registered
`ShapeAlreadyDefined`	409	Shape ID already exists for this class
`UnregisteredClassShape`	422	Shape required but not registered

System Errors

Code	Status	Description
`ParseError`	400	Invalid JSON in request body
`ValidationError`	422	Request validation failed
`IntegerOverflow`	422	Numeric operation would overflow
`ServiceUnavailable`	503	System is overloaded or shutting down

Examples

Bad Request (400)

Invalid JSON:

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

Not Found (404)

Container doesn’t exist:

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

Conflict (409)

Idempotency key already used with different content:

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

Unprocessable Entity (422)

Insufficient balance:

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

Service Unavailable (503)

System overloaded:

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

HTTP API - Endpoint reference
Transactions - Request structure
Operations by Domain - Operation-specific errors