statuscodes

Documentation

Overview

Package statuscodes is an attempt to create very-high-level buckets/classifications of errors, for two and ONLY two purposes:

1. Categories are intended for super-high-level bucketing of the responsibility for errors, ideally to be used for SLOs/success rate metrics on dashboards/reporting (availability).
2. Codes are intended for high-level bucketing of categories of errors, so that generic framework-level http/grpc clients can identify basic things like retriability, without understanding a ton of nuanced error codes.

For sending service-specific errors, please wrap one of these errors into a more specific error type with your service-specific errors. For example, bad_request.go has been added to this package, which wraps the basic BadRequest status code with more detailed information about the specific fields in question.

Index

• type StatusCategory
  • func (i StatusCategory) String() string
• type StatusCode
  • func FromString(s string) (StatusCode, bool)
  • func (re StatusCode) Category() StatusCategory
  • func (i StatusCode) String() string
  • func (re *StatusCode) UnmarshalText(text []byte) error

Types

type StatusCategory

type StatusCategory int

StatusCodes map directly into StatusCategories by the numeric range of the status code. See StatusCode comments for more details.

const (
	CategoryOK          StatusCategory = 1
	CategoryClientError StatusCategory = 2
	CategoryServerError StatusCategory = 3
)

func (StatusCategory) String

func (i StatusCategory) String() string

type StatusCode

type StatusCode int

const (
	// Keep OK not as zero so you know someone affirmatively picked it
	OK StatusCode = 600

	// The 700-swath is for Client-caused error responses
	// BadRequest is for when the caller has provided input data that does not pass validation.  This is expected to
	// fail in all retry scenarios -- the caller needs to change the input data to succeed.
	BadRequest StatusCode = 700
	// Unauthorized is for when the caller has presented no or invalid credentials.
	Unauthorized StatusCode = 701
	// Forbidden is for when the caller has presented valid credentials to SOMETHING in the system, but they
	// specifically do not have access to the referred item.
	Forbidden StatusCode = 702
	// NotFound is for when the document attempting to be fetched or updated is not found.
	NotFound StatusCode = 703
	// Conflict should be used for when there is a conflict between the incoming data and the data existing in a
	// storage system (database, etc.), very similar to a BadRequest call (and it is similarly not expected to be
	// successfully retriable unless someone changes the data in the source system via another call).
	// Deprecated: In retrospect, this inclusion is a mistake compared to just having it be a nuance of BadRequest.
	Conflict StatusCode = 704
	// RateLimited is expected to be used when the client (or a set of clients) is/are sending too many requests that
	// are flooding the server.  It is expected that the client will back off for some duration and then try again.
	// Well-behaved services will even return an expected duration for the client to retry-after.
	RateLimited StatusCode = 705
	// ClientConnectionSevered is for when the client was going to make a request but the connection has been severed.
	// This can occur when a service is using a client to connect to a downstream service. When making the request
	// it is not sent because the connection has been severed.
	ClientConnectionSevered StatusCode = 706

	// The 800-swath is for Server-caused error responses
	// InternalServerError is for when something otherwise uncategorizable has blown up inside the service logic.
	// This usually represents either a bug or an issue with a downstream system that the service is unable to
	// gracefully handle.  InternalServerErrors may or may not be retriable, it is unknown without more context.
	InternalServerError StatusCode = 800
	// NotImplemented is for when an endpoint exists and input appears valid, but the business logic behind it has
	// specifically not been implemented yet, but may exist in the future.  Without a further release of the service,
	// this error should not be retriable.
	NotImplemented StatusCode = 801
	// Unavailable is for when the server is experiencing a condition that is making all service temporarily
	// unavailable.  This error is potentially retriable, but the duration for backoff is unknown.
	Unavailable StatusCode = 802
	// UnknownError was intended to be a catchall error type for server-side issues.
	// Deprecated: In reality server-side errors should fall into one of the above 3 errors, and this inclusion was
	// a mistake.  It's not worth a breaking change to revoke at this time, though, so it shall live on.
	UnknownError StatusCode = 803
	// DeadlineExceeded is for when the server is unable to complete the request within the configured deadline and the
	// request times out. This error is retriable, but the duration for backoff is unknown.
	DeadlineExceeded StatusCode = 804
)

Notes:

1. DO NOT EXTEND THIS LIST WITHOUT VERY CAREFUL CONSIDERATION. Please read the package description at the top of this file to understand the intent of these error codes (and categories).
2. Don't overlap with HTTP error codes so people know that these are not HTTP error codes when they see them in server/service logs.

func FromString

func FromString(s string) (StatusCode, bool)

func (StatusCode) Category

func (re StatusCode) Category() StatusCategory

func (StatusCode) String

func (i StatusCode) String() string

func (*StatusCode) UnmarshalText

func (re *StatusCode) UnmarshalText(text []byte) error