Response-Header Reference

Every /v1/chat/completions response carries a set of SPASS-* headers that expose stack-internal state in a machine-friendly way. They follow the convention from ADR 0006: proper-cased on the wire (Spass-Augment-Applied), case-insensitive per RFC 9110, no X--prefix per RFC 6648, structured-field-values per RFC 8941.

Two categories: request-side (what the caller can send) and response-side (what the server emits).

Request-side headers

Response-side headers

Build/version

Request-correlation

Caller-Tip (Cut 2.23c+): Wenn ihr einen X-Request-Id-Header zum Server schickt, übernimmt der Server diesen Wert für audit.jsonl — euer eigener Trace-Identifier ist dann in unseren Logs für post-mortem-Korrelation findbar. Bei 5xx-Errors wird der request_id im dgx_code-Feld der Error-Response mitgeliefert (siehe errors.md).

Augmentation visibility (ADR 0006)

Attachment + document processing (CR-012 + CR-0015)

Set on chat responses that carried attachments. Absent when no attachment was processed.

Resolution + routing (ADR 0007 + 0008)

Cost-Pipeline V2 (ADR 0010)

On /a1/agents/<name>/chat and /a1/agents/<name>/sessions/<sid>/messages, all of the above are summed across the rig agent's internal /v1 sub-calls (Cut 2.7). The dominant Source wins (Upstream > Free > Zero > Unknown); Available is false if ANY sub-call was Unknown.

Recursion + audit-correlation (Cut 2.3)

/c1/chat only

/a1 agent-sessions only (Cut 2.12)

Quota signaling (Cut 2.32, CR-0005)

Caller-pattern: cost-tracking

function requestCostEur(headers: Headers): number | null {
  if (headers.get("spass-cost-available") !== "true") return null;
  return parseFloat(headers.get("spass-cost-eur") ?? "0");
}

Local-zero responses set Spass-Cost-Eur: 0.00 + Spass-Cost-Source: zero explicitly so the caller doesn't need to special-case missing headers.

Caller-pattern: routing-diagnose

const backend = headers.get("spass-resolved-backend");
const reason = headers.get("spass-resolved-reason");
if (reason === "primary-down-fallback") {
  // T1 unprefixed alias fell to cloud — log + maybe retry differently
}

Spass-Resolved-Reason removes the need to compare Spass-Resolved-Backend to the catalog manually — the server already did that.

Cross-references

• ADR 0006 — naming convention
• ADR 0007 — cost + backend-resolution V1
• ADR 0008 — slug tier-schema (T1/T2/T3/T4)
• ADR 0010 — cost-pipeline V2 (EUR + tenant-markup)
• /v1/info — model catalog with primary backend + capabilities
• /api/version — current build SHA + timestamp

SPASS-Notice — the answer is complete, but here is how it came about

Since 2026-08-22 a successful response (HTTP 200) may carry a SPASS-Notice header. It means the answer is usable but the server took a non-obvious path to produce it. There is no error, nothing failed, and no retry is needed.

Streaming: a header cannot be set once the first chunk is out, so the same information arrives as a named SSE event before the final content — spass.tool-cap, spass.tool-anti-loop, spass.tool-stripped, spass.tool-feedback-recovery, spass.tool-feedback-exhausted, spass.safety-fallback, spass.tool-salvaged, spass.prior-recovery. Until 2026-08-22 only the first four were emitted; the rest were dropped silently in streaming mode although they reached the caller in the unary body.

Migrating from dgx_code: the value is identical — read the header (or the SSE event) instead of the body field. Payload stays in the body: stripped_tool_names, feedback_retries.