Common Errors

These errors typically show up when sending Actor messages or applying commands.

UNDEFINED_<ACTOR>_TYPE

UNDEFINED_<ACTOR>_TYPE occurs when you try to create an Actor using a type that is not defined in the Registry.

HTTP/1.1 500 Internal Server Error
---
{
  "errors": [
    {
      "code": "UNDEFINED_TICKET_TYPE",
      "message": "Ticket type \u0027return8\u0027 is not defined",
      "details": {}
    }
  ]
}

FIX: Use a valid type key in your create message.

ALREADY_EXISTS

ALREADY_EXISTS occurs when you try to create an Actor with an ID that already exists in Hantera. All actor instance IDs must be unique.

HTTP/1.1 500 Internal Server Error
---
{
    "errors": [
        {
            "code": "ALREADY_EXISTS",
            "message": "",
            "details": {}
        }
    ]
}

FIX: Use new when creating an Actor to automatically generate a GUID.

NOT_FOUND

NOT_FOUND occurs when you query an Actor using an ID that does not exist. It also shows up if you try to create an Actor with an ID that is not a valid GUID.

HTTP/1.1 404 Not Found
---
{
  "errors": [
    {
      "code": "NOT_FOUND",
      "message": "",
      "details": {}
    }
  ]
}

FIX: Use new when creating an actor instance to automatically generate a unique and valid GUID.

INVALID_MESSAGE_BODY

INVALID_MESSAGE_BODY occurs when you do not specify the type key for an Asset or a Ticket.

HTTP/1.1 400 Bad Request
---
{
    "errors": [
        {
            "code": "INVALID_MESSAGE_BODY",
            "message": "The TypeKey field is required.",
            "details": {}
        }
    ]
}

INVALID_COMMAND

INVALID_COMMAND occurs when you send an applyCommands request which is missing some required information.

HTTP/1.1 500 Internal Server Error
---
{
  "errors": [
    {
      "code": "INVALID_COMMAND",
      "message": "The ItemTypeKey field is required.",
      "details": {}
    }
  ]
}

FIX: Carefully read the error message to discover and include the required keys.

DUPLICATE_ID

DUPLICATE_ID occurs when you try to use an already-existing external reference when creating a new Actor.

HTTP/1.1 500 Internal Server Error
---
{
  "errors": [
    {
      "code": "DUPLICATE_ID",
      "message": "A given ID is already in use",
      "details": {}
    }
  ]
}

FIX: Use unique external references across Actors.

Common Pitfalls

Not running h_ manage signals

h_ manage signals is a CLI command that returns latest Graph changes. After applying a Type definition, always run this command to see the changes.

Signals also return errors that may stop an Actor from being indexed by the Graph. For instance, h_manage signals catches when graphSetName is not set or when a node does not have a required edgeName. This way, you can troubleshoot and resolve type definition bugs fast.