Documentation
¶
Overview ¶
Package errors classifies failures the way every service shares: it gives a provider-agnostic vocabulary for why an operation failed, so a caller can tell a transient failure (worth retrying) from a permanent one (retrying will never help).
Import it under a name of its own where the standard library's errors package is also needed, for example:
import errs "github.com/gojargo/jargo/utils/errors"
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExtractHTTPStatusCode ¶
ExtractHTTPStatusCode returns the HTTP status an error carries, walking the wrapped chain for the first error that reports one. The second result is false when nothing in the chain carries a status.
An error implementing StatusCoder is asked. A provider SDK reports a refusal through a type of its own instead, so the rest of the chain is read for the status such a type puts on it: the field names below, on a response the error carries and then on the error itself.
Types ¶
type Category ¶
type Category string
Category is why an operation failed, independent of the provider that failed it. The zero value means nobody has said yet, which invites the category to be worked out from the error.
const ( // Unset is the zero value: the cause has not been decided yet. Unset Category = "" // Unknown means the cause could not be determined. Unknown Category = "unknown" // Authentication means credentials are missing or invalid. Authentication Category = "authentication" // Authorization means credentials are valid but lack access to the resource. Authorization Category = "authorization" // InvalidRequest means the request itself is malformed or names something // that does not exist, such as an unknown model or voice. InvalidRequest Category = "invalid_request" // RateLimit means too many requests were sent in too short a window. RateLimit Category = "rate_limit" // Quota means the account's credit or usage allowance is exhausted. Quota Category = "quota" // Connectivity means the service could not be reached. Connectivity Category = "connectivity" // Server means the provider reported an internal failure. Server Category = "server" // Application means application code failed, not the provider. Reported by a // service on behalf of code it invoked (a tool handler, say) whose failures // say nothing about the service's own health. Application Category = "application" )
The categories a failure can fall into.
func ClassifyError ¶
ClassifyError classifies an error by the HTTP status it carries, falling back to Connectivity for a failure to reach the service at all, and to Unknown for anything unrecognized. A provider raising failures its own way needs its own classification.
func ClassifyHTTPStatusCode ¶
ClassifyHTTPStatusCode classifies an HTTP status code, returning Unknown for a code that carries no provider-independent meaning.
func (Category) IsPermanent ¶
IsPermanent reports whether the failure will keep recurring until something changes.
A permanent failure gives the same result every time it is retried: the credentials stay rejected, the request stays malformed. Only new credentials or settings can clear it, so retrying is pointless.
type HTTPStatusError ¶
type HTTPStatusError struct {
// Status is the HTTP status the provider refused with.
Status int
// Err is the underlying failure, whose message this error carries.
Err error
}
HTTPStatusError is an error carrying the HTTP status a provider refused with, for a caller that has a status and no error type of its own to put it on.
func NewHTTPStatusError ¶
func NewHTTPStatusError(status int, err error) *HTTPStatusError
NewHTTPStatusError builds an HTTPStatusError carrying status and wrapping err.
func (*HTTPStatusError) HTTPStatusCode ¶
func (e *HTTPStatusError) HTTPStatusCode() int
HTTPStatusCode implements StatusCoder.
func (*HTTPStatusError) Unwrap ¶
func (e *HTTPStatusError) Unwrap() error
Unwrap returns the underlying failure.
type StatusCoder ¶
type StatusCoder interface {
error
// HTTPStatusCode returns the status the provider refused with.
HTTPStatusCode() int
}
StatusCoder is implemented by an error carrying the HTTP status a provider refused with. It is what ExtractHTTPStatusCode looks for as it walks an error chain, so a provider that wants its refusals classified reports them through an error implementing this.
Source Files