API Errors

Encore supports returning structured error information from your APIs using the encore.dev/beta/errs package.

Errors are propagated across the network to the generated clients and can be used within your front-ends without having to build any custom marshalling code.

The errs.Error type

Structured errors are represented by the errs.Error type:

type Error struct {
	// Code is the error code to return.
	Code ErrCode `json:"code"`
	// Message is a descriptive message of the error.
	Message string `json:"message"`
	// Details are user-defined additional details.
	Details ErrDetails `json:"details"`
	// Meta are arbitrary key-value pairs for use within
	// the Encore application. They are not exposed to external clients.
	Meta Metadata `json:"-"`
}

Returning an *errs.Error from an Encore API endpoint will result in Encore serializing this struct to JSON and returning it in the response. Additionally Encore will set the HTTP status code to match the error code (see the mapping table below).

For example:

return &errs.Error{
	Code: errs.NotFound,
	Message: "sprocket not found",
}

Causes Encore to respond with a HTTP 404 error with body:

{
    "code": "not_found",
    "message": "sprocket not found",
    "details": null
}

Error Wrapping

Encore applications are encouraged to always use the errs package to manipulate errors. It supports wrapping errors to gradually add more error information, and lets you easily define both structured error details to return to external clients, as well as internal key-value metadata for debugging and error handling.

func Wrap(err error, msg string, metaPairs ...interface{}) error

Use errs.Wrap to conveniently wrap an error, adding additional context and converting it to an *errs.Error. If err is nil it returns nil. If err is already an *errs.Error it copies the Code, Details, and Meta fields over.

The variadic metaPairs parameter must be key-value pairs, where the key is always a string and the value can be any built-in type. Existing key-value pairs from the err are merged into the new *Error.

func WrapCode(err error, code ErrCode, msg string, metaPairs ...interface{}) error

errs.WrapCode is like errs.Wrap but also sets the error code.

func Convert(err error) error

errs.Convert converts an error to an *errs.Error. If the error is already an *errs.Error it returns it unmodified. If err is nil it returns nil.

Error Codes

The errs package defines error codes for common error scenarios. They are identical to the codes defined by gRPC for interoperability.

The table below summarizes the error codes. You can find additional documentation about when to use them in the package documentation.

Error Building

In cases where you have complex business logic, or multiple error returns, it's convenient to gradually add metadata to your error.

For this purpose Encore provides errs.Builder. The builder lets you gradually set aspects of the error, using a chaining API design. Use errs.B() to get a new builder that you can start chaining with directly.

When you want to return the constructed error call the .Err() method.

For example:

func getBoard(ctx context.Context, boardID int64) (*Board, error) {
    // Construct a new error builder with errs.B()
	eb := errs.B().Meta("board_id", params.ID)

	b := &Board{ID: params.ID}
	err := sqldb.QueryRow(ctx, `
		SELECT name, created
		FROM board
		WHERE id = $1
	`, params.ID).Scan(&b.Name, &b.Created)
	if errors.Is(err, sqldb.ErrNoRows) {
        // Return a "board not found" error with code == NotFound
		return nil, eb.Code(errs.NotFound).Msg("board not found").Err()
	} else if err != nil {
        // Return a general error
		return nil, eb.Cause(err).Msg("could not get board").Err()
	}
    // ...
}

Inspecting API Errors

When you call another API within Encore, the returned errors are always wrapped in *errs.Error.

You can inspect the error information either by casting to *errs.Error, or using the below helper methods.

func Code(err error) ErrCode

errs.Code returns the error code. If the error was not an *errs.Error it returns errs.Unknown.

func Meta(err error) Metadata
type Metadata map[string]interface{}

errs.Meta returns any structured metadata present in the error. If the error was not an *errs.Error it returns nil. Unlike when you return error information to external clients, all the metadata is sent to the calling service, making debugging even easier.

func Details(err error) ErrDetails

errs.Details returns the structured error details. If the error was not an *errs.Error or the error lacked details, it returns nil.