POST During Outage
On this page 5 sections
QSCS will never replay a POST (or any other state-changing method) from its cache, that would corrupt your application data. While an upstream is degraded, QSCS short-circuits write requests with a deterministic "soft-fail" response, so that well-behaved clients can retry safely later.
What the client sees
HTTP/1.1 503 Service Unavailable
X-QSCS-Mode: headless
X-QSCS-Headless-Reason: post_soft_fail
Content-Type: application/json
Content-Length: …
{
"error": "upstream_unavailable",
"retry": true,
"reason": "origin_degraded",
"host": "example.com",
"uri": "/api/checkout"
}The body is always JSON and always contains the same five fields. Application code can rely on the shape.
Why this is better than a generic 502
The soft-fail response says three useful things at once:
- This was QSCS, not your origin. The headers
X-QSCS-Mode: headlessandX-QSCS-Headless-Reason: post_soft_failmake that unambiguous. - Retrying later will succeed.
"retry": truetells well-behaved clients (mobile apps, queues) to back off and try again rather than alerting the user. - The original request was never sent upstream. So nothing was half-applied.
What clients should do
| Client type | Recommended behaviour |
|---|---|
| Browser app | Show a non-scary "Saving…" message; retry the request after a small delay; surface a generic error only if multiple retries fail. |
| Mobile app | Queue the request locally with exponential backoff. Most outages clear within a minute or two. |
| Server-to-server | Honour the JSON contract: parse retry; on true, requeue with backoff. On false (rare), treat as a fatal upstream failure. |
Idempotency notes
QSCS does not de-duplicate retries, that is your application's responsibility. If your write endpoints are not idempotent, consider attaching a client-generated request ID and ignoring duplicate IDs server-side.
Tuning the trigger
The degraded state is entered after two consecutive upstream failures and cleared after two consecutive successful probes. These thresholds are fixed in the current release and tuned to avoid both flapping and slow detection.