fix: UTXO endpoint to return 404 for not found

Author: m0wer

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+- Fixed UTXO endpoint to return HTTP 404 (Not Found) instead of 500 (Internal Server Error) when UTXO is not found
+- Added proper error type handling for API errors:
+  - `NotFoundError` returns HTTP 404
+  - `BadRequestError` returns HTTP 400
+  - Invalid address or txid parameters now return 400 instead of 500
+
 ## [0.6.0] - 2026-01-08
 
 ### Removed

neutrino_server/internal/api/handler.go

@@ -7,6 +7,7 @@ import (
 	"bytes"
 	"encoding/hex"
 	"encoding/json"
+	"errors"
 	"net/http"
 	"strconv"
 
@@ -239,7 +240,17 @@ func (h *Handler) handleGetUTXO(w http.ResponseWriter, r *http.Request) {
 
 	report, err := h.node.GetUTXO(txid, uint32(vout), address, startHeight)
 	if err != nil {
-		h.errorResponse(w, http.StatusInternalServerError, err.Error())
+		// Check for typed errors to return appropriate status codes
+		var notFoundErr *neutrino.NotFoundError
+		var badRequestErr *neutrino.BadRequestError
+
+		if errors.As(err, &notFoundErr) {
+			h.errorResponse(w, http.StatusNotFound, err.Error())
+		} else if errors.As(err, &badRequestErr) {
+			h.errorResponse(w, http.StatusBadRequest, err.Error())
+		} else {
+			h.errorResponse(w, http.StatusInternalServerError, err.Error())
+		}
 		return
 	}
 

neutrino_server/internal/neutrino/errors.go

@@ -0,0 +1,40 @@
+package neutrino
+
+import "fmt"
+
+// NotFoundError represents an error when a requested resource is not found.
+// This should result in HTTP 404 responses.
+type NotFoundError struct {
+	Resource string
+	Message  string
+}
+
+func (e *NotFoundError) Error() string {
+	if e.Message != "" {
+		return e.Message
+	}
+	return fmt.Sprintf("%s not found", e.Resource)
+}
+
+// NewNotFoundError creates a new NotFoundError.
+func NewNotFoundError(resource string, message string) *NotFoundError {
+	return &NotFoundError{
+		Resource: resource,
+		Message:  message,
+	}
+}
+
+// BadRequestError represents an error due to invalid client input.
+// This should result in HTTP 400 responses.
+type BadRequestError struct {
+	Message string
+}
+
+func (e *BadRequestError) Error() string {
+	return e.Message
+}
+
+// NewBadRequestError creates a new BadRequestError.
+func NewBadRequestError(message string) *BadRequestError {
+	return &BadRequestError{Message: message}
+}

neutrino_server/internal/neutrino/node.go

@@ -397,13 +397,13 @@ func (n *Node) GetUTXO(txid string, vout uint32, address string, startHeight int
 	}
 
 	if address == "" {
-		return nil, errors.New("address is required: neutrino uses compact block filters which match on scripts, not outpoints")
+		return nil, NewBadRequestError("address is required: neutrino uses compact block filters which match on scripts, not outpoints")
 	}
 
 	// Parse the address to get the pkScript
 	addr, err := btcutil.DecodeAddress(address, n.chainParams)
 	if err != nil {
-		return nil, fmt.Errorf("invalid address %s: %w", address, err)
+		return nil, NewBadRequestError(fmt.Sprintf("invalid address %s: %v", address, err))
 	}
 
 	pkScript, err := txscript.PayToAddrScript(addr)
@@ -414,7 +414,7 @@ func (n *Node) GetUTXO(txid string, vout uint32, address string, startHeight int
 	// Parse txid
 	targetHash, err := chainhash.NewHashFromStr(txid)
 	if err != nil {
-		return nil, fmt.Errorf("invalid txid: %w", err)
+		return nil, NewBadRequestError(fmt.Sprintf("invalid txid: %v", err))
 	}
 
 	n.logger.Infof("Looking up UTXO %s:%d for address %s starting from height %d", txid, vout, address, startHeight)
@@ -513,7 +513,7 @@ func (n *Node) GetUTXO(txid string, vout uint32, address string, startHeight int
 
 	// Build response
 	if foundTx == nil {
-		return nil, fmt.Errorf("UTXO not found: ensure start_height is at or before the block containing the transaction")
+		return nil, NewNotFoundError("UTXO", "UTXO not found: ensure start_height is at or before the block containing the transaction")
 	}
 
 	report := &UTXOSpendReport{}