Troubleshooting

This guide helps you diagnose and resolve common issues when working with Shield.

Transaction Submission Issues

Problem: "Fee not paid to Shield" Error

{
    "result": null,
    "error": {
        "code": -32001,
        "message": "No output to Shield payment address detected"
    },
    "id": "1"
}

Possible Causes:

• No output to Shield payment address

• Payment sent to incorrect Shield address

• Multiple Shield outputs in transaction

Solutions:

1. Verify you're using the current Shield payment address from /info

2. Ensure your transaction includes an output to this address

3. Check that you're including only one Shield payment output

4. Verify the address is exactly correct (including case and checksum)

Problem: "Fee below minimum required" Error

{
    "result": null,
    "error": {
        "code": -32002,
        "message": "Fee below minimum required"
    },
    "id": "1"
}

Possible Causes:

• Fee amount is too low for the chosen fee rate

• Fee calculation error in transaction creation

Solutions:

1. Re-check fee calculation: Transaction Size (vbytes) × Fee Rate (sats/vbyte)

2. Ensure you're factoring in the complete transaction size

3. Use a higher fee rate from the /info endpoint

4. For large transactions, consider increasing the fee rate further

Problem: "Transaction decode failed" Error

{
    "result": null,
    "error": {
        "code": -32000,
        "message": "Unable to decode the transaction"
    },
    "id": "1"
}

Possible Causes:

• Malformed transaction hex

• Incomplete transaction data

• Encoding issues

Solutions:

1. Verify the transaction is correctly serialized

2. Check for truncation in the hex string

3. Ensure the transaction is properly signed

4. Try re-serializing the transaction

Problem: Transaction Accepted but Not Appearing in Blockchain

Possible Causes:

• Low fee rate relative to network congestion

• Mining pool policy restrictions

• Transient network issues

Solutions:

1. Wait longer - Shield transactions bypass the mempool but still depend on miners

2. Try submitting a new transaction with a higher fee rate

3. Check if the transaction has dependencies that aren't confirmed

4. Verify the transaction doesn't conflict with chain or pool policies

API Connection Issues

Problem: Cannot Connect to Shield API

Possible Causes:

• Network connectivity issues

• DNS resolution problems

• SSL/TLS errors

Solutions:

1. Check your internet connection

2. Verify DNS resolution for shield.rebarlabs.io

3. Ensure your client supports TLS 1.2 or higher

4. Try connecting from a different network

Problem: Rate Limit Exceeded Errors

HTTP/1.1 429 Too Many Requests

Possible Causes:

• Too many requests in a short time period

• Shared IP address with other users

• No backoff strategy implemented

Solutions:

1. Implement rate limiting in your client code

2. Add exponential backoff for retries

3. Cache responses where appropriate (e.g., /info endpoint)

4. Contact support for enterprise rate limits if needed

Problem: Timeouts on API Requests

Possible Causes:

• Shield service under high load

• Network latency issues

• Client timeout settings too aggressive

Solutions:

1. Increase client-side timeout values

2. Implement retry logic with backoff

3. Check for any network issues between your client and Shield

4. Try a different network connection if possible

Transaction Confirmation Issues

Problem: Transaction Not Confirming

Possible Causes:

• Fee rate too low for current network conditions

• Transaction has dependencies that aren't confirmed

• Mining pool policies rejecting the transaction

Solutions:

1. Wait longer - Bitcoin confirmation times can vary significantly

2. If urgent, create a replacement transaction with higher fees

3. Check block explorers to see if transaction is visible (may indicate it was broadcast to network)

4. Verify transaction doesn't have any policy violations

Problem: Transaction Shows in Block Explorer but Status Unclear

Possible Causes:

• Transaction confirmed but client hasn't updated

• Temporary chain reorganization

• Block explorer data lag

Solutions:

1. Check multiple block explorers

2. Wait for additional confirmations

3. Verify the transaction in your own Bitcoin node if available

4. Check transaction details match what you submitted

Fee and Payment Issues

Problem: Unexpected Fee Amounts

Possible Causes:

• Fee calculation error

• Transaction size estimated incorrectly

• Fee rates changed between fetching info and submission

Solutions:

1. Re-verify your fee calculation logic

2. Fetch updated fee information before each transaction

3. Check if you're accounting for all transaction parts in size calculation

4. Consider adding a small buffer to calculated fees

Problem: Cannot Determine Correct Shield Payment Address

Possible Causes:

• Not fetching from /info endpoint

• Caching old address information

• Network request failures

Solutions:

1. Always fetch current payment information from /info before each transaction

2. Implement proper error handling for API requests

3. Set reasonable cache TTLs if caching payment information

4. Log the address being used for debugging

Contacting Support

If you're still experiencing issues after trying these troubleshooting steps, contact Shield support:

1. Email: [email protected]

2. Include detailed information:

   • Error messages and codes

   • Transaction hex (if applicable)

   • Request and response examples

   • Timestamp of the issue

   • Steps to reproduce the problem

Diagnostic Tools

Use these diagnostic commands to help troubleshoot issues:

Check Shield API Status

# Get current fee information
curl -v https://shield.rebarlabs.io/info

Verify Transaction State

If your transaction has been confirmed, you can check its status with Bitcoin block explorers:

• mempool.space

• blockstream.info

• blockchain.com