Delivery outcomes and recovery

HTTP activity is not delivery completion.

A short Relay or Cache submission returns its usual HTTP status and JSON. For a long-running admitted request, the current implementation starts an HTTP 200 response after five seconds, sets X-OpenPayload-Delivery-Wait: true, and flushes newline keepalives. The completed body contains whitespace followed by one JSON result.

Once response bytes have started, the HTTP status cannot change. Wait for the complete response framing, parse the final JSON, and check its result fields. A heartbeat, HTTP 200 alone, or interrupted JSON does not confirm delivery or storage.

For a Relay, inspect http_status, success, delivery_mode, and code. For a Cache, require accepted: true and check the terminal status when present. An error or missing acceptance flag is not successful storage. A policy handoff means the next Relay accepted responsibility; it does not confirm later storage.

Save the handle before a disconnect.

An admitted submission exposes three response headers: X-OpenPayload-Submission-Id for correlation, X-OpenPayload-Receipt-Url for the local result route, and X-OpenPayload-Receipt-Token for authorized access. Preserve them as soon as your HTTP client receives headers.

The receipt token is a bearer credential. Keep it private and use it only with the matching operator endpoint. A result receipt contains outcome metadata, not the original envelope or an acknowledgement from the recipient.

The current alpha retains receipt records for one hour, subject to its bounded record capacity. Missing, invalid, or expired receipt credentials return 404; that does not prove delivery failed.

Ask the node what it recorded.

Use GET /relay/submissions/{receiptId} or GET /cache/submissions/{receiptId}, with the receipt token in its request header. Replace the example origin, receipt identifier, and token below with those from the same submission. The example token is a placeholder.

GET https://relay.example.com/relay/submissions/<receiptId>
X-OpenPayload-Receipt-Token: <receipt-token>

An active result returns HTTP 202 with state: processing. A completed result returns HTTP 200 with state: complete, the terminal http_status, and result. Evaluate that nested result using the same success or acceptance rules as the original submission.

{
  "state": "complete",
  "http_status": 202,
  "result": {
    "success": true,
    "delivery_mode": "cache_offload"
  }
}

This is an abbreviated result shape. A node restart can leave a pending record with state: unknown; it does not fabricate success or grant permission to retry. A sender disconnect does not itself cancel processing owned by the node.