POST During Outage
On this page 3 sections
POST, PUT, PATCH and DELETE operations execute at the application origin. QSCS does not queue them for later execution or automatically repeat them after a lost result. An application may explicitly declare a POST query read-only so that an eligible saved result can be returned during an upstream transport failure.
An unavailable operation result
HTTP/1.1 503 Service Unavailable
X-QSCS-Mode: headless
X-QSCS-Headless-Reason: operation_result_unavailable
Content-Type: application/json
Cache-Control: no-store
{
"error": "upstream_unavailable",
"retry": false,
"requestMayHaveCompleted": true,
"reason": "origin_unreachable",
"host": "example.com",
"uri": "/api/checkout"
}
A transport failure can occur after the origin has executed the request. This response is not evidence that the operation was rejected or never sent. Check the application's operation status before resubmitting, or use an application-defined idempotency key. QSCS does not de-duplicate arbitrary business operations.
Explicitly read-only POST results
The read-only continuity policy requires QSCS 4.3.16 or newer. Update serving nodes before relying on this behavior.
For a query endpoint whose POST requests have no business side effects, the backend can return:
HTTP/1.1 200 OK
Content-Type: application/json
X-QSCS-Post-Replay: read-only
Cache-Control: private, max-age=60
{"report": "read-only result"}
The origin's default policy honors this explicit declaration. Retention is bounded by the declared max-age and the configured maximum result age. Alternatively, the account's operator can declare selected read-only POST paths in Infrastructure → origin → API settings → Configure read-only POSTs, after acknowledging the warning. Disabled prevents storage and reuse. See the policy controls.
Never declare payments, checkout, transfers, updates or other writes read-only. A saved response does not execute a new operation. The configuration cannot determine your application's business semantics.
Every healthy request still reaches the origin. Only an upstream transport failure permits an unexpired saved result for the exact URL, POST body, identity and application-header context. An HTTP response from the origin, including a 5xx error, remains authoritative and is returned. Successful JSON responses with unsafe privacy/framing/representation headers are not retained; no-store, no-cache, no-transform, Set-Cookie and partial responses prevent reuse. Explicit live-request directives and conditional requests also bypass it.
A reused result is marked X-QSCS-Headless-Reason: read_only_post_replay and X-QSCS-Post-Replay-Age. It reports earlier observed data, not newly executed work. The memory-only snapshot is separate from the client's delta baseline, archival history and application idempotency records; expiration, eviction or restart may remove it. Identity gates and application permissions remain in force, and GET federation permissions are not expanded to POST.
Client handling
Check status, content type and the operation's application result. Treat an unavailable write result as uncertain. Do not automatically resubmit a business write merely because the connection failed or QSCS returned 503. A read-only query may use the declared continuity policy when showing older data is acceptable. Show the recorded age where freshness matters.