Documentation
¶
Overview ¶
Package httperr classifies HTTP errors into transient and permanent based on objective HTTP/REST semantics.
Transient errors are those where retrying the same request may succeed: network failures, timeouts, rate limits, server errors (5xx).
Permanent errors are those where retrying is pointless: bad request (400), unauthorized (401), not found (404), etc.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNetwork indicates a transport-level failure: TCP, DNS, TLS. // The request never reached the server or the connection was interrupted. ErrNetwork = errors.New("httperr: network error") // ErrTimeout indicates the request or response exceeded a deadline. // Covers both client-side timeouts and HTTP 408 Request Timeout. ErrTimeout = errors.New("httperr: timeout") // ErrRateLimit indicates the server rejected the request due to // rate limiting (HTTP 429 Too Many Requests). ErrRateLimit = errors.New("httperr: rate limit") // ErrServerError indicates a server-side failure (HTTP 5xx). // The server acknowledged the request but failed to process it. ErrServerError = errors.New("httperr: server error") )
Sentinel errors for transient HTTP failures. Use with longrun.TransientRule or errors.Is for classification.
Functions ¶
func Classify ¶
Classify wraps err with a transient sentinel when the error is objectively retryable per HTTP/REST semantics. Permanent errors are returned as-is.
Classification order:
- nil → nil
- context.DeadlineExceeded or *url.Error with timeout → ErrTimeout
- *net.OpError or *net.DNSError → ErrNetwork
- StatusCoder with 408 → ErrTimeout
- StatusCoder with 429 → ErrRateLimit
- StatusCoder with 5xx → ErrServerError
- Everything else → returned unchanged (permanent)
The original error is always preserved in the chain via fmt.Errorf("%w: %w"), so callers can still use errors.As to access the underlying typed error.
Example:
resp, err := httpClient.Do(req)
if err != nil {
return httperr.Classify(err)
}
func ClassifyStatus ¶
ClassifyStatus maps an HTTP status code to a transient sentinel. Non-transient codes return the original error unchanged.
func TransientErrors ¶
func TransientErrors() []error
TransientErrors returns all sentinel errors that represent objectively transient HTTP failures per REST semantics.
Useful for building github.com/thumbrise/longrun or custom retry logic without depending on pkg/longrun directly.
Returned errors: ErrNetwork, ErrTimeout, ErrRateLimit, ErrServerError.
Types ¶
type StatusCoder ¶
type StatusCoder interface {
StatusCode() int
}
StatusCoder is implemented by HTTP error types that carry a status code. Standard library does not define this interface, but many HTTP clients (including go-github) return errors with a Response.StatusCode field.
Implement this interface on your HTTP error types to enable automatic classification by Classify.
Source Files