Status Codes & Errors
Every status code the daemon emits, sorted by what triggers it.
2xx
| Code | When |
|---|
200 OK | Cached or upstream response. Also returned for OPTIONS and the no-origin health-check fallback. |
| (upstream-passthrough 2xx) | Whatever the origin returns is forwarded verbatim with CORS headers added. |
3xx
| Code | When |
|---|
3xx | Upstream redirect. Forwarded verbatim with Location preserved; never cached. |
4xx
| Code | When |
|---|
400 Bad Request | Method other than GET / HEAD / POST / OPTIONS, or unparseable HTTP request line. |
401 Unauthorized | Origin has Auth=identity and no authenticated QSCS identity. Body: {"error":"not authenticated"}. |
404 Not Found | (a) /qscs/metrics requested from a non-loopback peer. (b) Host not in [Origins] and no matching static page and origins are configured. (c) /api/identity/status with an unknown UUID. |
5xx
| Code | When |
|---|
503 Service Unavailable | HEADLESS with no cached body (X-QSCS-Headless-Reason: no_cache), or POST while upstream is degraded/unreachable (X-QSCS-Headless-Reason: post_soft_fail, JSON body). |
| (upstream-passthrough 5xx) | Whatever the origin returns is forwarded; the failure does not automatically count as a health failure (only TCP-level / read-write faults do). |
Error body shapes
Errors that originate inside the daemon are always JSON:
{ "error": "<short reason string>" }
HEADLESS POST soft-fail uses the larger structured shape documented in HEADLESS Behaviour:
{
"error": "upstream_unavailable",
"retry": true,
"reason": "origin_unreachable" | "origin_degraded",
"host": "<host>",
"uri": "<uri>"
}
