Skip to main content

Troubleshooting

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

Transaction Submission Issues​

"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)

"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

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​

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

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

Timeouts on API Requests​

Possible Causes:​

  • Shield service under high load
  • Network latency issues
  • Client timeout settings too aggressive

Solutions:​

  • Increase client-side timeout values
  • Implement retry logic with backoff
  • Check for any network issues between your client and Shield
  • Try a different network connection if possible

Transaction Confirmation Issues​

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

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​

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

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

Verify Transaction State​

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