KMS - Error 500 Internal Server Error

When attempting to sign Mainnet transactions using Tatum KMS, you may encounter the following error response:

{
    "status": 500,
    "statusText": "Internal Server Error",
    "data": { "message": "Server Error" }
}
//logs may also include:
Transaction not found on external system. ID: ####

This issue occurs because the Four-Eye Principle is not enabled.

🚧

Attention

Implementing The four-eye principle mechanism is mandatory for signing transactions on Mainnet.

Root Cause

Tatum KMS enforces the Four Eye Principle for added security when signing transactions on the Mainnet. If this validation mechanism is not set up, KMS will refuse to sign the transaction, resulting in a 500 Internal Server Error.

Solution: Enable the Four-Eye Principle

To resolve this error, you must implement the Four-Eye Principle by configuring an external validation server.

Steps to Enable:

1. Set Up an External Validation Server
   • Deploy an application that maintains a list of valid transaction IDs to sign.
   • Ensure this server can handle HTTP GET requests for transaction validation.
2. Configure Tatum KMS to Use the External URL
   • Modify your KMS configuration to include the --externalUrl parameter:
     Shell

      tatum-kms daemon --externalUrl=<http://your-external-server.com>
     

   • Replace http://your-external-server.com with the actual URL of your validation server.
3. Ensure the External Server Returns the Correct Response
   • When KMS requests validation for a transaction, the external server must respond:
     • 2xx (e.g., 200 OK) → The transaction is valid, and KMS will proceed with signing.
     • Any other response → KMS will reject the transaction.

Example Flow

1. KMS fetches a transaction from Tatum.
2. KMS sends a GET request to your_external_url/transaction_id.
3. If the response is 200 OK, KMS signs the transaction.
4. If the response is not 200 OK, the transaction is skipped, triggering the 500 Internal Server Error.

📘

Note

Additional information is available in this article.