Errors
The errors Serve returns, the HTTP status each one maps to, and what a client sees.
Engine.Serve returns either a response or an error. Errors are sentinel values wrapped with %w, so compare with errors.Is. Two helpers do the mapping for adapters: weir.StatusCode(err) gives the HTTP status, and weir.RetryAfter(err) gives a retry hint when there is one. weirhttp.WriteError uses both.
What clients see
| Status | Cause |
|---|---|
| 400 | request failed validation (bad host, path, escape, oversized target); no store or origin cost |
| 501 | CONNECT or a protocol upgrade reached weirhttp.Handler (Middleware passes them on) |
| 502 | origin error with no usable stale entry |
| 503 | shed (with Retry-After), breaker open with no usable stale entry, or the engine closed |
| 499 | the client went away; a log hint only, adapters write nothing |
| 504 | origin timeout, must-revalidate entry that could not be validated, or only-if-cached with nothing stored |
Sentinels
| Sentinel | Message | Status |
|---|---|---|
ErrInvalidConfig | weir: invalid config | not a request error: returned by New, SetMode and Purge |
ErrInvalidRequest | weir: invalid request | 400 |
ErrShed | weir: origin capacity exhausted | 503 with Retry-After |
ErrCircuitOpen | weir: origin circuit open | 503 |
ErrOriginTimeout | weir: origin timeout | 504 |
ErrMustRevalidate | weir: must-revalidate response could not be validated | 504 |
ErrOnlyIfCached | weir: only-if-cached and no stored response | 504 |
ErrOrigin | weir: origin error | 502 |
ErrClosed | weir: engine closed | 503 |
ErrUpgradeNotSupported | weir: connect and protocol upgrades not supported | 501 |
ErrEagerUnsupported | weir: store cannot scrub; epoch written, delete skipped | not a request error: returned by Purge with Eager on a store that cannot scrub |
This table is read from errors.go at build time. *OriginError wraps the transport error from the origin and matches ErrOrigin. *RetryError carries ErrShed or ErrCircuitOpen with the retry hint.
An origin that answers with its own 5xx is not an error from Serve: the response is passed through, or replaced by a stale entry when stale-if-error allows.
Messages
Error messages start with weir: (or store: from the store package), are lowercase and have no trailing punctuation. They are for logs. Match on the sentinel, not the text.