Error Model

Asset Core uses standard HTTP status codes with RFC 9457 Problem Details error responses. This reference describes the error model and common error conditions. It is designed to be stable so clients can build predictable retry and remediation logic.

Overview

Errors are returned as application/problem+json payloads with a stable taxonomy, machine-readable codes, and optional retry guidance. The HTTP status code indicates the error category, while the body provides specifics. Treat the code field as the canonical machine-readable identifier.

Structure

Write/Read Error Response (Problem Details)

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

Error Detail Fields

Field	Type	Description
type	string	RFC 9457 type URI (Asset Core uses urn:assetcore:error:\CODE“)
title	string	Short error class name (ValidationError, NotFoundError)
status	integer	HTTP status code
detail	string	Human-readable explanation
code	string	Machine-readable error identifier (SCREAMING_SNAKE_CASE)
retryable	boolean	Whether clients should retry
retry_after_ms	integer	Optional retry-after hint in milliseconds (429/503)
hint	string	Optional remediation hint
auth_reason	string	Optional auth denial reason (only when disclosure is reason_code)
server_correlation_id	string	Optional server-assigned correlation ID
client_correlation_id	string	Optional client-provided correlation ID
details	object	Optional structured details
core_error	object	Optional serialized core error payload (write daemon only)

Fields

HTTP Status Codes

Status	Meaning	When Used
200 OK	Success	Request completed successfully
400 Bad Request	Invalid request	Malformed JSON, missing fields
401 Unauthorized	Unauthenticated	Missing or invalid bearer token
403 Forbidden	Not permitted	Principal lacks permission or namespace access
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
425 Too Early	Stale read	Minimum world sequence not reached (read endpoints)
429 Too Many Requests	Rate limited	Quota or auth rate limits
500 Internal Server Error	Server error	Unexpected failures
503 Service Unavailable	Temporarily unavailable	Overloaded, shutting down

Common Error Codes

Container Errors

Code	Status	Description
CONTAINER_NOT_FOUND	404	The specified container doesn’t exist
CONTAINER_ALREADY_EXISTS	409	Container ID is already in use
WRONG_CONTAINER_KIND	422	Operation not supported for this container kind

Balance Errors

Code	Status	Description
INVALID_QUANTITY	422	Quantity must be greater than zero
INSUFFICIENT_BALANCE	422	Not enough balance for the operation
INVALID_OPERATION	422	Operation would overflow or is invalid

Instance Errors

Code	Status	Description
INSTANCE_NOT_FOUND	404	The specified instance doesn’t exist
ALREADY_ATTACHED	409	Instance already has a parent
NOT_ATTACHED	422	Instance has no parent to detach from
HAS_CHILDREN	422	Must detach children before burning
WOULD_CREATE_CYCLE	422	Attachment would create a cycle

Slot Errors

Code	Status	Description
SLOT_OUT_OF_BOUNDS	422	Slot index exceeds container capacity
SLOT_OCCUPIED	409	Slot already contains an instance
SLOT_EMPTY	422	Slot doesn’t contain an instance

Schema Errors

Code	Status	Description
UNREGISTERED_CLASS	404	The specified class isn’t registered
CLASS_ALREADY_EXISTS	409	Class ID is already registered
SHAPE_ALREADY_REGISTERED	409	Shape already exists for this class
UNREGISTERED_CLASS_SHAPE	422	Shape required but not registered

System Errors

Code	Status	Description
INVALID_REQUEST	400	Malformed JSON or invalid parameters
PAYLOAD_TOO_LARGE	413	Request body exceeds configured limits
UNSUPPORTED_MEDIA_TYPE	415	Content-Type is not JSON
INTEGER_OVERFLOW	500	Numeric overflow (bug)
SERVICE_UNAVAILABLE	503	System is overloaded or shutting down

Examples

Bad Request (400)

Invalid JSON:

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

Not Found (404)

Container doesn’t exist:

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

Conflict (409)

Idempotency key already used with different content:

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

Unprocessable Entity (422)

Insufficient balance:

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

Service Unavailable (503)

System overloaded:

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

Related references

• HTTP API - Endpoint reference
• Transactions - Request structure
• Action Reference - Operation-specific errors