feat: add project-owned error catalogs and HTTP 200 failure contracts

errors/errors.go

@@ -8,10 +8,12 @@ import (
 // APIError is the public error shape used by handlers and middleware.
 // Cause is retained for logging and unwrapping, but is never serialized.
 type APIError struct {
-	Status  int
-	Code    string
-	Message string
-	Cause   error
+	Status       int
+	Code         string
+	Message      string
+	Cause        error
+	BusinessCode any // Optional public code resolved from a project catalog.
+	reference    bool
 }
 
 func (e *APIError) Error() string {
@@ -68,6 +70,9 @@ func From(err error) *APIError {
 	}
 	var apiErr *APIError
 	if stdErrors.As(err, &apiErr) && apiErr != nil {
+		if apiErr.reference {
+			return Internal(err)
+		}
 		return apiErr
 	}
 	return Internal(err)