TrogonError

TrogonError is a Go library that brings structured, secure error handling to distributed systems based on the Straw Hat Error Specification.

TrogonError provides standardized error codes, rich metadata, and visibility controls to create consistent error handling across service boundaries. It goes beyond simple error messages to include contextual information, retry guidance, and internationalization support while implementing a three-tier visibility system to control error disclosure.

TrogonError addresses the critical challenge of inconsistent error handling in distributed systems, where different services often use incompatible error formats. It prevents information leakage through visibility controls, enables effective debugging with error chaining and metadata, and improves user experience with localized messages and help links.

TrogonError is particularly valuable for teams building microservices, REST APIs, or gRPC services that require consistent error responses. Enterprise development teams benefit from its secure error handling with controlled information disclosure, while DevOps and SRE teams leverage its rich metadata for debugging distributed systems.

TrogonError provides structured error handling with:

• Standardized error codes mapped to common failure scenarios
• Rich metadata for debugging and error correlation
• Three-tier visibility system (Internal/Private/Public) for secure information disclosure
• Error chaining and stack traces for comprehensive debugging
• Internationalization support for user-facing error messages
• Retry guidance with duration or absolute time specifications
• Help links for enhanced user experience
• Template system for consistent error definitions across services

Getting Started

Installation

go get github.com/TrogonStack/trogonerror

Production Templates (Recommended)

For production applications, use error templates to ensure consistency and maintainability. You may define platform-specific error templates in a separate package and import them into your application. As well as define your own error templates for your application.

import (
"context""github.com/TrogonStack/trogonerror"
)
// Define reusable error templatesvar (
ErrUserNotFound=trogonerror.NewErrorTemplate("shopify.users", "NOT_FOUND",
trogonerror.TemplateWithCode(trogonerror.CodeNotFound))
ErrValidationFailed=trogonerror.NewErrorTemplate("shopify", "VALIDATION_FAILED",
trogonerror.TemplateWithCode(trogonerror.CodeInvalidArgument))
ErrOrderNotCancellable=trogonerror.NewErrorTemplate("shopify.orders", "ORDER_NOT_CANCELLABLE",
trogonerror.TemplateWithCode(trogonerror.CodeFailedPrecondition))
ErrDatabaseError=trogonerror.NewErrorTemplate("shopify", "DATABASE_ERROR",
trogonerror.TemplateWithCode(trogonerror.CodeInternal))
)
typeGetUserstruct {
UserIDstring
}
funcGetUserHandler(ctx context.Context, cmdGetUser) (*User, error) {
user, err:=db.FindUser(ctx, "SELECT * FROM users WHERE id = $1", cmd.UserID)
iferr!=nil {
iferrors.Is(err, sql.ErrNoRows) {
// This is a common pattern for not found errorsreturnnil, ErrUserNotFound.NewError(
trogonerror.WithMetadataValuef(trogonerror.VisibilityPublic, "userId", "gid://shopify/Customer/%s", cmd.UserID))
}
// This is a common pattern for database errorsreturnnil, ErrDatabaseError.NewError(
trogonerror.WithWrap(err))
}
// ... rest of the logic
}
typeCreateUserstruct {
Emailstring
}
funcCreateUserHandler(ctx context.Context, cmdCreateUser) (*User, error) {
ifcmd.Email=="" {
// This is a common pattern for validation errorsreturnnil, ErrValidationFailed.NewError(
trogonerror.WithSubject("/email"),
trogonerror.WithMessage("email is required"),
trogonerror.WithMetadataValue(trogonerror.VisibilityPublic, "validationType", "REQUIRED"))
}
// ... rest of the logic
}
typeCancelOrderstruct {
OrderIDstring
}
funcCancelOrderHandler(ctx context.Context, cmdCancelOrder) error {
order, err:=db.FindOrder(ctx, "SELECT * FROM orders WHERE id = $1", cmd.OrderID)
// ... rest of the logiciforder.Status=="delivered" {
// This is a common pattern for failed precondition errorsreturnErrOrderNotCancellable.NewError(
trogonerror.WithMetadataValuef(trogonerror.VisibilityPublic, "orderId", "gid://shopify/Order/%s", cmd.OrderID),
trogonerror.WithMetadataValue(trogonerror.VisibilityPublic, "reason", "ALREADY_DELIVERED"),
trogonerror.WithHelpLinkf("Order Management", "https://admin.shopify.com/orders/%s", cmd.OrderID))
}
// ... rest of the logic
}

Basic Usage without Template Errors

import"github.com/TrogonStack/trogonerror"funcmain() {
// Create a simple error with clear domain and uppercase reasonerr:=trogonerror.NewError("shopify.users", "NOT_FOUND",
trogonerror.WithCode(trogonerror.CodeNotFound),
trogonerror.WithMetadataValue(trogonerror.VisibilityPublic, "userId", "gid://shopify/Customer/1234567890"),
trogonerror.WithMetadataValue(trogonerror.VisibilityInternal, "requestedBy", "storefront-api"),
trogonerror.WithMetadataValue(trogonerror.VisibilityInternal, "shopId", "mystore.myshopify.com"))
fmt.Println(err.Error()) // "resource not found"fmt.Println(err.Domain()) // "shopify.users"fmt.Println(err.Reason()) // "NOT_FOUND"
}