User-facing vs. logged errors

[ryan0x44]

As a service owner, I want as much information as possible about errors that occur, but I might not always want to reveal details to consumers of my service.

For example, say you service has a database error pq: invalid input syntax for integer: \"b\".

1. You want your API to return a HTTP Status of 500 with Content-Type of application/problem+json and body:

{
  "type": "https://example.net/internal-server-error",
  "title": "Internal Server Error",
  "code": 6001
}

2. You want your service to log something like this:

2017-08-08T19:03:46.706Z  ERROR    somefile.go:70       database query error
     {"endpoint": "Profiles", "code": "6001", "err": "pq: invalid input syntax for integer: \"b\""}

Right now, the Endpoint interface returns interface{}, error which means to add data such as an error code, we either need to do one of:

1. add it to the response struct (first return value)
2. have a custom error type which we type assert
3. embed it in the error string itself
4. in the transport layer, have a mapping which augments error data

I'm not sure how to best achieve this with Go kit, and feel like it's something Go kit could provide (more) guidance on. From this issue, I'm hoping to PR some documentation to help with that.

[peterbourgon]

Errors returned by endpoints should probably indicate transport errors that are worth retrying. That's because it's the only mechanism that safety-style middlewares like circuit breakers and rate limiters have to determine what to do with a given request. Business-domain errors should probably be baked in to your response struct, using whatever degree and depth of context is appropriate for you.

I'm happy to work this into a FAQ entry, or look at your attempt to do the same.

[terinjokes]

Hey @ryan0x44!

In my microservices, I return the error as part of the Endpoint's {}interface response. Then, while encoding in the Transport, I check if the response has an error. For this I have an errorer interface, lifted from the shipping example:

type errorer interface {
	error() error
}

func encodeHTTPResponse(ctx context.Context, w http.ResponseWriter, response interface{}) error {
	if e, ok := response.(errorer); ok && e.error() != nil {
		err := e.error()

		// encode HTTP error
        return nil
	}

	// ...
}

By this point the full error message has already been handled by logging middleware, so there's no additional work needed to log it here.

[ryan0x44]

Thanks @peterbourgon and @terinjokes ! I'm still trying to grok how to handle logging the detailed error and returning the user-friendly error.

Is "worth retrying" the best way to delineate these errors?

• Response struct error = business-logic errors (e.g. validation issues) = this will definitely fail if you retry the same request
• Error value = transient errors (e.g. db connection issues, service busy, etc) = you should retry this request later

If so, could it be said that the former would be HTTP status codes not in 500, the latter would be HTTP status codes in the 500's?

Examples:

• Transport layer maps HTTP status codes from errors returned in either the Endpoint response struct or error value.
• DB errors would be returned by a Service as an error value, which would then be returned by an Endpoint as an error value.
• Business-domain errors such as "Exceeded valid number of social links on your profile" would be embedded on the response struct as an error.
• Endpoint errors such as "Invalid input; name cannot be empty" validation errors would also be embedded on the response struct as an error.

[handrews]

If so, could it be said that the former would be HTTP status codes not in 500, the latter would be HTTP status codes in the 500's?

The HTTP spec includes discussions of which codes are intended to be retry-able and under what circumstances and mechanisms (e.g. the Retry-After header). For instance, 411 has a straightforward fix and retry condition, while 409 responses SHOULD include enough information for the client to retry the fix successfully. 413 may be retry-able, and indicates that with Retry-After).

Ideally, any implementation would make it easy to follow the retry-able vs non-retry-able guidelines and mechanisms already present in HTTP.

[peterbourgon]

Is "worth retrying" the best way to delineate these errors?

Let's be more precise. If an error is returned by an endpoint, it's visible to endpoint middlewares and the transport layer; you can safely assume those layers might make decisions based on the presence of that error. If an error is enclosed in a response type, it's not visible‡ to endpoint middlewares or the transport layer; you can safely assume stock Go kit‡‡ won't make decisions based on the presence of that error.

Examples:

These all make sense to me on a quick skim.

—
‡ without explicit introspection e.g. type-asserting the response to an errorer interface
‡‡ you can of course provide code in your e.g. response encoder to check for an error

[handrews]

If an error is returned by an endpoint, it's visible to endpoint middlewares and the transport layer; you can safely assume those layers might make decisions based on the presence of that error. If an error is enclosed in a response type, it's not visible‡ to endpoint middlewares or the transport layer; you can safely assume stock Go kit‡‡ won't make decisions based on the presence of that error.

I think many of those non-transport errors in @ryan0x44 's examples still do somewhat map into the response codes:

• 500, 409, or 400 depending on the error DB errors would be returned by a Service as an error value, which would then be returned by an Endpoint as an error value.
• 409 Business-domain errors such as "Exceeded valid number of social links on your profile" would be embedded on the response struct as an error.
• 400 Endpoint errors such as "Invalid input; name cannot be empty" validation errors would also be embedded on the response struct as an error.

These database / business-domain / validation errors are additional information beyond the status code, which may be fairly specific (409) or very generic (400, 500). A 409 state conflict may show up as a database error (e.g. Foreign key constraint failure: you need to create object X before object Y, which can be fixed and retried). This is arguably more important to the client than the fact that the error occurred in the database (which is more important to the service developer).

[peterbourgon]

Yes. Any reasonably sophisticated service will want to introspect response types to extract errors, and map them to HTTP response codes (or the equivalent in whatever other transport is being used).