Error Codes

Shield returns standard Bitcoin Core error codes for compatibility, along with Shield-specific errors. This reference helps you understand and troubleshoot error responses.

JSON-RPC Error Format

Error responses follow the JSON-RPC 1.0 specification format:

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

Common Error Codes

Code	Message	Description	Solution
-32000	"Unable to decode the transaction"	Unable to decode the transaction hex string	Check the transaction is valid and meets consensus rules
-32001	"No output to Shield payment address detected"	No output to Shield payment address	Add an output to the Shield payment address from /infoendpoint
-32002	"Fee below minimum required"	Fee paid is below the minimum required	Increase the fee amount
-32003	"Multiple outputs to Shield payment address detected"	Multiple outputs to Shield payment address	Consolidate to a single output
-32004	"Transaction exceeds size limit"	Reduce transaction size	Add an output to the Shield payment address
-32005	"All mining pools have rejected this transaction"	This transaction had correct inputs, fee, and payment address but it was rejected by all mining pools	Check this transaction using testmempoolaccepton a core node with minrelayfee set to 0
-32006	"Unspent Satoshis detected in this transaction"	This transaction contains a fee that will cause it to propagate over the P2P network	Ensure the input value is equal to the output value
-32007	"One or more inputs to this transaction was not found"	Transaction is attempting to spend a UTXO that does not exist or has already been spent	Check transaction inputs. Note: Spending the output of a pending Shield transaction is a WIP feature and is not supported at this time
-32008	"Internal Error"	Unspecified error from the Shield server	Contact Rebar with your transaction ID for support

HTTP Status Codes

In addition to JSON-RPC error codes, Shield also uses HTTP status codes:

HTTP Status	Description
200	Success
400	Bad Request - The request could not be understood
401	Unauthorized - Authentication required
403	Forbidden - Insufficient permissions
404	Not Found - Resource does not exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Shield service error
503	Service Unavailable - Shield is temporarily unavailable

Troubleshooting Tips

1. Verify payment address: Always query the /info endpoint before sending transactions to ensure you have the current Shield payment address

2. Check fee calculation: Confirm your fee calculation is correct for the transaction size

3. Validate transaction format: Ensure your transaction is properly formatted and serialized

4. Handle temporary errors: For 5xx errors or code -103, implement retry logic with exponential backoff

5. Rate limiting: If you receive 429 responses or code -104, reduce your request frequency