Error Handling

Each route function must declare a return type of error. If there is no response payload, error will be the only return type. If there is a payload response, error will be the second and last return type.

The returned error, whether it's the default or custom, must NOT be a pointer.

When an error is returned as non-nil, the operation will be considered failed, and the error will be formatted according to rfc7807.

For example, this route function logic:

// @Method(GET)
// @Route(/default-error)
func (ec *MyController) DefaultError() error {
    return fmt.Errorf("default error")
}

Will be formatted to:

{

    "type":"Internal Server Error",
    "title":"",
    "detail":"Encountered an error during operation 'DefaultError'",
    "status":500,
    "instance":"/controller/error/DefaultError",
    "extensions":{
        "error":"default error"
    }

}

Custom HTTP Error

To override the default error format, define your own error struct and set whatever properties you like:

For example:

type CustomError struct {
	error
	Message string `json:"message"`
}

// @Method(GET)
// @Route(/custom-error)
func (mc *MyController) CustomError() CustomError {
	return CustomError{
		Message: "custom error",
	}
}

Will be formatted to:

{
    "message" : "custom error"
}

Custom HTTP error response code

By default, any error is returned with a 500 HTTP error code. To set a different code, use the SetStatus API.

For example:

// @Method(GET)
// @Route(/default-error)
func (mc *MyController) DefaultError() error {
    mc.SetStatus(runtime.StatusNotImplemented)
    return fmt.Errorf("default error")
}

Will return a 501 HTTP response code.