problem

Documentation

Index

• Variables
• func Inflate(ctx context.Context, p *P)
• func RegisterError(err error, p P)
• func Render(ctx context.Context, w http.ResponseWriter, p interface{})
• type HasProblem
• type P
  • func (p *P) Error() string

Variables

var (
	// NotFound is a well-known problem type.  Use it as a shortcut
	// in your actions.
	NotFound = P{
		Type:   "not_found",
		Title:  "Resource Missing",
		Status: http.StatusNotFound,
		Detail: "The resource at the url requested was not found.  This is usually " +
			"occurs for one of two reasons:  The url requested is not valid, or no " +
			"data in our database could be found with the parameters provided.",
	}

	// ServerError is a well-known problem type.  Use it as a shortcut
	// in your actions.
	ServerError = P{
		Type:   "server_error",
		Title:  "Internal Server Error",
		Status: http.StatusInternalServerError,
		Detail: "An error occurred while processing this request.  This is usually due " +
			"to a bug within the server software.  Trying this request again may " +
			"succeed if the bug is transient, otherwise please report this issue " +
			"to the issue tracker at: https://github.com/stellar/horizon/issues." +
			" Please include this response in your issue.",
	}

	// RateLimitExceeded is a well-known problem type.  Use it as a shortcut
	// in your actions.
	RateLimitExceeded = P{
		Type:   "rate_limit_exceeded",
		Title:  "Rate limit exceeded",
		Status: 429,
		Detail: "The rate limit for the requesting IP address is over its alloted " +
			"limit.  The allowed limit and requests left per time period are " +
			"communicated to clients via the http response headers 'X-RateLimit-*' " +
			"headers.",
	}

	// NotImplemented is a well-known problem type.  Use it as a shortcut
	// in your actions.
	NotImplemented = P{
		Type:   "not_implemented",
		Title:  "Resource Not Yet Implemented",
		Status: http.StatusNotFound,
		Detail: "While the requested URL is expected to eventually point to a " +
			"valid resource, the work to implement the resource has not yet " +
			"been completed.",
	}

	// NotAcceptable is a well-known problem type.  Use it as a shortcut
	// in your actions.
	NotAcceptable = P{
		Type: "not_acceptable",
		Title: "An acceptable response content-type could not be provided for " +
			"this request",
		Status: http.StatusNotAcceptable,
	}

	// BadRequest is a well-known problem type.  Use it as a shortcut
	// in your actions.
	BadRequest = P{
		Type:   "bad_request",
		Title:  "Bad Request",
		Status: http.StatusBadRequest,
		Detail: "The request you sent was invalid in some way",
	}

	// ServerOverCapacity is a well-known problem type.  Use it as a shortcut
	// in your actions.
	ServerOverCapacity = P{
		Type:   "server_over_capacity",
		Title:  "Server Over Capacity",
		Status: http.StatusServiceUnavailable,
		Detail: "This horizon server is currently overloaded.  Please wait for " +
			"several minutes before trying your request again.",
	}

	// Timeout is a well-known problem type.  Use it as a shortcut
	// in your actions.
	Timeout = P{
		Type:   "timeout",
		Title:  "Timeout",
		Status: http.StatusGatewayTimeout,
		Detail: "Your request timed out before completing.  Please try your " +
			"request again.",
	}

	// UnsupportedMediaType is a well-known problem type.  Use it as a shortcut
	// in your actions.
	UnsupportedMediaType = P{
		Type:   "unsupported_media_type",
		Title:  "Unsupported Media Type",
		Status: http.StatusUnsupportedMediaType,
		Detail: "The request has an unsupported content type. Presently, the " +
			"only supported content type is application/x-www-form-urlencoded.",
	}

	// BeforeHistory is a well-known problem type.  Use it as a shortcut
	// in your actions.
	BeforeHistory = P{
		Type:   "before_history",
		Title:  "Data Requested Is Before Recorded History",
		Status: http.StatusGone,
		Detail: "This horizon instance is configured to only track a " +
			"portion of the stellar network's latest history. This request " +
			"is asking for results prior to the recorded history known to " +
			"this horizon instance.",
	}

	// StaleHistory is a well-known problem type.  Use it as a shortcut
	// in your actions.
	StaleHistory = P{
		Type:   "stale_history",
		Title:  "Historical DB Is Too Stale",
		Status: http.StatusServiceUnavailable,
		Detail: "This horizon instance is configured to reject client requests " +
			"when it can determine that the history database is lagging too far " +
			"behind the connected instance of stellar-core.  If you operate this " +
			"server, please ensure that the ingestion system is properly running.",
	}
)

Well-known and reused problems below:

Functions

func Inflate

func Inflate(ctx context.Context, p *P)

Inflate expands a problem with contextal information. At present it adds the request's id as the problem's Instance, if available.

func RegisterError

func RegisterError(err error, p P)

RegisterError records an error -> P mapping, allowing the app to register specific errors that may occur in other packages to be rendered as a specific P instance.

For example, you might want to render any sql.ErrNoRows errors as a problem.NotFound, and you would do so by calling:

problem.RegisterError(sql.ErrNoRows, problem.NotFound) in you application initialization sequence

func Render

func Render(ctx context.Context, w http.ResponseWriter, p interface{})

Render writes a http response to `w`, compliant with the "Problem Details for HTTP APIs" RFC:

https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-00

`p` is the problem, which may be either a concrete P struct, an implementor of the `HasProblem` interface, or an error. Any other value for `p` will panic.

Types

type HasProblem

type HasProblem interface {
	Problem() P
}

HasProblem types can be transformed into a problem. Implement it for custom errors.

type P

type P struct {
	Type     string                 `json:"type"`
	Title    string                 `json:"title"`
	Status   int                    `json:"status"`
	Detail   string                 `json:"detail,omitempty"`
	Instance string                 `json:"instance,omitempty"`
	Extras   map[string]interface{} `json:"extras,omitempty"`
}

P is a struct that represents an error response to be rendered to a connected client.

func (*P) Error

func (p *P) Error() string