The following errors are applicable to all versions of the Universal Command Protocol (UCP).These errors are version-agnostic and may appear in any command that follows the UCP structure.In batch responses, if different HTTP status codes occur in the same batch, the HTTP response will return 207 Multi-Status.
1. General Errors#
| HTTP Status | Code | Description |
|---|
| 500 | -7000 | An unknown error occurred. |
| 500 | -7001 | Internal server error. See logs for more details. |
2. Network Errors#
| HTTP Status | Code | Description |
|---|
| 404 | -45000 | The specified network does not exist or is not recognized. |
3. Field Validation Errors#
| HTTP Status | Code | Description |
|---|
| 400 | -45100 | The request body must be a non-empty JSON array. |
| 400 | -45101 | Each entry in the request array must be a JSON object. |
| 400 | -45102 | The protocol version in the request does not match the expected value. |
| 409 | -45103 | Duplicate externalId found in the batch request. |
| 422 | -45105 | externalId is required for batch operations. |
| 422 | -45106 | A required field is missing in the request. |
| 422 | -45107 | A field must be explicitly set to null. |
| 422 | -45108 | A numeric field must be zero or positive. |
| 422 | -45109 | A field has an invalid data type. |
| 422 | -45110 | A field has an invalid value. The value does not match the expected type. |
| 422 | -45111 | A field does not match the required pattern or format. |
4. Preimage and Signature Errors#
| HTTP Status | Code | Description |
|---|
| 422 | -45120 | The preimage must be empty for this command. |
| 422 | -45121 | A specific field is required in the preimage. |
| 422 | -45122 | A specific preimage field must be null. |
| 422 | -45123 | A preimage field has the wrong data type. |
| 422 | -45124 | A metadata value is not a string. All metadata values must be strings. |
| 422 | -45125 | The number of items in the preimage does not match the expected size. |
| 422 | -45126 | Required fields are missing in the preimage. |
| 422 | -45127 | Preimage contains unexpected extra fields. |
| 422 | -45128 | The public key is mandatory in this command. |
| 422 | -45129 | The public key must be Base64-encoded. |
| 422 | -45130 | The public key must be in valid UDBN format. |
| 422 | -45131 | The signature must be Base64-encoded. |
| 422 | -45132 | Signature verification failed. Content could not be validated. |
| 404 | -45133 | The address is not registered. Use the keys.register command to register it. |
| 422 | -45134 | The address is in an invalid state for this operation. |
5. Command Errors#
| HTTP Status | Code | Description |
|---|
| 400 | -45201 | This command is not supported. |
| 404 | -45202 | This command is not recognized or implemented. |
6. TOTP Errors#
| HTTP Status | Code | Description |
|---|
| 422 | -45300 | TOTP is not supported for this command. |
| 422 | -45301 | TOTP is required for this command. Provide it in the 'ghost' object. |
| 422 | -45302 | TOTP is not enabled for this address. |
| 422 | -45303 | The provided TOTP code is invalid. |
| 409 | -45304 | This public key is already registered. Use keys.get to retrieve details. |
| 422 | -45305 | An error occurred during TOTP validation. |
| 409 | -45306 | TOTP is already enabled for this address. |
| 404 | -45307 | The address was not found. |
| 422 | -45308 | The provided owner name contains invalid characters. |
7. Element Errors#
| HTTP Status | Code | Description |
|---|
| 409 | -45400 | An element with this name already exists and is active. |
| 404 | -45401 | The element was not found. |
| 403 | -45402 | You do not have permission to update this element. |
| 422 | -45403 | Element name is invalid. It must follow strict format rules. |
| 422 | -45404 | Element name cannot have more than 5 segments. |
| 422 | -45405 | Each name segment must be between 2 and 12 characters long. |
| 422 | -45406 | Name segments cannot start or end with an underscore. |
| 422 | -45407 | Each segment must contain at least one letter. |
| 422 | -45408 | Name cannot contain consecutive underscores. |
| 422 | -45409 | Name cannot contain consecutive dots. |
| 422 | -45410 | Name cannot start or end with a dot. |
| 422 | -45411 | Name cannot contain 4 or more identical characters in a row. |
| 422 | -45412 | Name contains invalid characters. Only A–Z, 0–9, underscore (_) and dot (.) are allowed. |
| 403 | -45413 | Element is disabled. Operation not allowed. |
| 423 | -45414 | Element is temporarily locked. |
| 403 | -45415 | Element is blocked due to security or policy enforcement. |
| 409 | -45416 | Element is already in the requested status. No change was made. |
8. Permission Errors#
| HTTP Status | Code | Description |
|---|
| 403 | -45420 | Element owner cannot be assigned transaction or agent permissions. |
| 409 | -45421 | This address already has the specified permission for the element. |
| 404 | -45422 | No permissions found for this address. |
| 404 | -45423 | The requested permission does not exist for this address. |
9. Meter Errors#
| HTTP Status | Code | Description |
|---|
| 422 | -45430 | The provided meter category is invalid. |
| 422 | -45431 | The specified unit is not allowed in the selected meter category. |
| 422 | -45432 | Initial supply cannot exceed maximum supply. |
10. Transaction Errors#
| HTTP Status | Code | Description |
|---|
| 403 | -45440 | You do not have permission to create transactions for this element. |
| 422 | -45441 | Sender and receiver addresses must be different. |
11. Balance Errors#
| HTTP Status | Code | Description |
|---|
| 422 | -45450 | Transaction amount cannot be zero. |
| 422 | -45451 | Transaction amount cannot be negative. |
| 422 | -45452 | This element type does not support balance operations. |
| 422 | -45453 | Insufficient funds in the source address to complete the transaction. |
Modified at 2025-10-15 18:32:25
