Documentation
¶
Overview ¶
Package errors provides a curated list of standard types of failures you'll likely encounter when executing RPC handlers. There are almost 40 failure status codes in standard HTTP which leads to a lot of confusion about which to use in certain cases. To simplify this decision making, the errors package only exposes a dozen or so types of failures that we'll map to an appropriate HTTP/RPC status for you. They represent the most common types of failure you're likely to encounter. Should you need something beyond this, the New() function accepts any status you feel like generating.
Index ¶
- func IsAlreadyExists(err error) bool
- func IsBadCredentials(err error) bool
- func IsBadRequest(err error) bool
- func IsInternalServiceError(err error) bool
- func IsNotFound(err error) bool
- func IsPermissionDenied(err error) bool
- func IsThrottled(err error) bool
- func IsTimeout(err error) bool
- func IsUnavailable(err error) bool
- func IsUnexpected(err error) bool
- func Status(err error) int
- type RPCError
- func AlreadyExists(messageFormat string, args ...interface{}) RPCError
- func BadCredentials(messageFormat string, args ...interface{}) RPCError
- func BadRequest(messageFormat string, args ...interface{}) RPCError
- func InternalServerError(messageFormat string, args ...interface{}) RPCError
- func New(status int, messageFormat string, args ...interface{}) RPCError
- func NotFound(messageFormat string, args ...interface{}) RPCError
- func PermissionDenied(messageFormat string, args ...interface{}) RPCError
- func Throttled(messageFormat string, args ...interface{}) RPCError
- func Timeout(messageFormat string, args ...interface{}) RPCError
- func Unavailable(messageFormat string, args ...interface{}) RPCError
- func Unexpected(messageFormat string, args ...interface{}) RPCError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsAlreadyExists ¶ added in v1.1.3
IsAlreadyExists returns true if the underlying HTTP status code of 'err' is 409. This will be true for any error you created using the AlreadyExists() function.
func IsBadCredentials ¶ added in v1.1.3
IsBadCredentials returns true if the underlying HTTP status code of 'err' is 401. This will be true for any error you created using the BadCredentials() function.
func IsBadRequest ¶ added in v1.1.3
IsBadRequest returns true if the underlying HTTP status code of 'err' is 400. This will be true for any error you created using the BadRequest() function.
func IsInternalServiceError ¶ added in v1.1.3
IsInternalServiceError returns true if the underlying HTTP status code of 'err' is 500. This will be true for any error you created using the InternalServiceError() function.
func IsNotFound ¶ added in v1.1.3
IsNotFound returns true if the underlying HTTP status code of 'err' is 404. This will be true for any error you created using the NotFound() function.
func IsPermissionDenied ¶ added in v1.1.3
IsPermissionDenied returns true if the underlying HTTP status code of 'err' is 403. This will be true for any error you created using the PermissionDenied() function.
func IsThrottled ¶ added in v1.1.3
IsThrottled returns true if the underlying HTTP status code of 'err' is 429. This will be true for any error you created using the Throttled() function.
func IsTimeout ¶ added in v1.1.3
IsTimeout returns true if the underlying HTTP status code of 'err' is 408. This will be true for any error you created using the Timeout() function.
func IsUnavailable ¶ added in v1.1.3
IsUnavailable returns true if the underlying HTTP status code of 'err' is 503. This will be true for any error you created using the Unavailable() function.
func IsUnexpected ¶ added in v1.1.3
IsUnexpected returns true if the underlying HTTP status code of 'err' is 500. This will be true for any error you created using the Unexpected() function.
Types ¶
type RPCError ¶
type RPCError struct {
// HTTPStatus is the HTTP status code that most closely describes this error.
HTTPStatus int `json:"status"`
// Message is the human-readable error message.
Message string `json:"message"`
}
RPCError is an error that encodes a human-readable message as well as a status that corresponds to the closest HTTP status code. For instance if the failure was due to an inability to find a resource/record/etc, status would be 404.
This type of error can be recognized by 'github.com/monadicstack/respond' in order to automatically send proper failures and statuses without extra lifting.
func AlreadyExists ¶
AlreadyExists is a 409-style error that is used when attempting to create some record/resource, but there is already a duplicate instance in existence.
func BadCredentials ¶
BadCredentials is a 401-style error that indicates that the caller either didn't provide credentials when necessary or they did, but the credentials were invalid for some reason. This corresponds to the HTTP "unauthorized" status, but we prefer this name because this type of failure has nothing to do with authorization and it's more clear what aspect of the request has failed.
func BadRequest ¶
BadRequest is a 400-style error that indicates that some aspect of the request was either ill-formed or failed validation. This could be an ill-formed function parameter, a bad HTTP body, etc.
func InternalServerError ¶
InternalServerError is a generic 500-style catch-all error for failures you don't know what to do with.
func New ¶
New creates an error that maps directly to an HTTP status so if your RPC call results in this error, it will result in the same 'status' in your HTTP response. While you can do this for more obscure HTTP failure statuses like "payment required", it's typically a better idea to use the error functions BadRequest(), PermissionDenied(), etc as it provides proper status codes and results in more readable code.
func NotFound ¶
NotFound is a 404-style error that indicates that some record/resource could not be located.
func PermissionDenied ¶
PermissionDenied is a 403-style error that indicates that the caller does not have rights/clearance to perform any part of the operation.
func Throttled ¶
Throttled is a 429-style error that indicates that the caller has exceeded the number of requests, amount of resources, etc allowed over some time period. The failure should indicated to the caller that the failure is due to some throttle that prevented the operation from even occurring.
func Timeout ¶
Timeout is a 408-style error that indicates that some operation exceeded its allotted time/deadline.
func Unavailable ¶
Unavailable is a 503-style error that indicates that some aspect of the server/service is unavailable. This could be something like DB connection failures, some third party service being down, etc.
func Unexpected ¶ added in v1.1.3
Unexpected is a generic 500-style catch-all error for failures you don't know what to do with. This is exactly the same as calling InternalServerError(), just more concise in your code.
Source Files