Response headers identify a request, explain model selection and expose cache or control decisions. Read the presence condition for each header: a missing value does not necessarily mean the feature is disabled.
Request identity#
Use the two request IDs for different forms of correlation.
| Header | Meaning | Presence and constraints |
|---|---|---|
X-Request-ID |
Log correlation ID | Accepts a caller value of 1–128 letters, digits, ., _ or -; otherwise the gateway generates one |
X-Pointsman-Request-ID |
Gateway-generated request UUID | Set before early refusals, including 401 and accounting/intake 503s; joins usage, provider dispatch and reservation records |
X-Requested-Model |
Requested model after whitespace stripping | Describes the request, not the serving model |
A supplied X-Pointsman-Request-ID is ignored. Reusing X-Request-ID does not reuse the gateway UUID. If the client disconnects before receiving headers, it cannot recover that attempt's UUID from the response.
Cache outcome#
Cache headers describe the path taken by the request.
| Header | Value | Presence |
|---|---|---|
X-Cache |
MISS, HIT-L1 or HIT-L2 |
Cache outcome on the response path; L1 is exact, L2 is semantic |
X-Cache-Threshold |
Required semantic similarity, default 0.92 |
Only when a semantic tier is configured for the request modality |
X-Cache-Semantic |
Reason listed below | Explains whether semantic lookup ran or was skipped |
Semantic reason vocabulary#
Interpret the reason together with X-Cache.
| Reason | Meaning |
|---|---|
consulted |
Semantic lookup ran |
not-consulted |
Exact cache already answered |
skipped-short |
Text is below the semantic minimum length |
skipped-temperature |
Sampling policy excluded reuse; default exact-only excludes nonzero or omitted temperature |
skipped-tools |
Request declares tools |
skipped-window |
Embedding-window eligibility could not be established; also includes bounded eligibility-work refusal |
skipped-mutable-image |
Remote image URL is not cacheable |
skipped-circuit-open |
L2 breaker skipped embedding and index lookup |
replay-refused |
Cached serving model was outside the caller's allow set; request routed as a miss |
bypassed |
Request directive skipped lookup |
disabled |
Cache path disabled |
unready |
Required cache capability not ready |
error |
Cache operation failed |
See cache behavior for eligibility and failure policy.
Model resolution and routing#
These headers appear when the corresponding decision occurred.
| Header | Meaning | Presence |
|---|---|---|
X-Resolved-Model |
Annotated resolution result | Resolution changed the requested name |
X-Model-Resolution |
How the request was served or substituted | Resolution/fallback path supplied a reason |
X-Routing-Mode |
Selected smart-routing mode | Smart-routed request |
X-Semantic-Group |
Group selected by prompt meaning | No explicit model or applicable key default; match cleared the threshold |
X-Semantic-Score |
Winning cosine similarity, four decimal places | With X-Semantic-Group |
X-Attempted-Models |
Models attempted in order | Request entered the fallback ladder; pre-attempt substitution alone has no attempted models |
X-Resolved-Model is annotated, for example:
X-Resolved-Model: gpt-4o-mini (normalized from "GPT-4O-MINI")
Reasons include alias, prefix, normalized, redirect, default, fallback, substituted, smart:<mode> and semantic. Do not treat the complete value as a bare model name. X-Provider-Model, when present, describes the provider-reported name instead.
A health exclusion before any attempt can report fallback(<model> -> <served>, pre-attempt, unavailable) without X-Attempted-Models. The reason does not disclose whether another caller's traffic opened a breaker or caused cooldown.
Limits and guardrails#
Control headers are conditional on a matching rule or action.
| Header | Meaning | Presence |
|---|---|---|
X-RateLimit-Remaining-Requests |
Tightest remaining request headroom across applicable rules | A request-count rule matched |
X-RateLimit-Remaining-Tokens |
Tightest remaining token headroom across applicable rules | A token-count rule matched |
X-Degraded |
Limit-rule substitution, <from>-><to> |
A degrade action selected another model |
X-Guardrail-Result |
Guardrail action | A rule acted |
The request and token headroom headers are independent. Absence means no rule of that metric matched this request, not a promise of unlimited capacity.
Outcome-learning feedback#
Only an outcome-learning routing decision supplies feedback headers. A direct model request has none. A non-learning group such as weighted-random can log a decision without returning a feedback handle.
| Header | Purpose | Attribution boundary |
|---|---|---|
X-Decision-Id |
Bare decision identifier | Uses the originating gateway's in-process memo |
X-Decision-Receipt |
Signed receipt for the same decision | Carries attribution so another gateway instance can process feedback |
Send either value as decision_id when rating an answer; prefer the receipt when requests can reach different instances. If neither header exists, there is no outcome-learning decision to rate.
Treat a receipt as opaque. Its security and lifetime properties are:
- Signed, not encrypted: holders can decode sampling key, served arm, routing provenance and trace IDs.
- Caller-bound: the requesting API key is bound into the signature; another key cannot use it.
- Time-bounded: it expires with
pointsman.bandit.decision-memory-ttl-min, default 15 minutes. - Revision-aware:
v3.includes decision time and sealing time so receipt and bare-ID feedback refer to the same decision. Olderv2.receipts remain accepted until expiry.
Serving identity#
Use serving evidence separately from the originally requested name.
| Header | Meaning | Presence and limits |
|---|---|---|
X-Served-Provider |
Provider that answered | Synchronous provider response or first live-stream chunk; absent on cache hits |
X-Served-Generation |
Admitted reasoning_effort or thinking_mode setting |
Model row fixes that setting; synchronous, buffered and first live-stream decoration. Also set on synchronous cache hits; that cache case lacks separate test coverage |
X-Provider-Model |
Sanitized provider-reported model | Synchronous provider-served response; absent on live streams and cache hits |
X-Provider-Model retains at most 96 characters and replaces characters outside [A-Za-z0-9._:/@+-]. It is identity evidence, not the billing identity. An unexpected reported name leaves usage unverified; see compatibility.
Experimental quality routing#
These headers apply only to the corresponding opt-in quality feature.
| Header | Meaning | Presence |
|---|---|---|
X-Quality-Route |
Served model was qualified or the declared baseline, with reason, profile and policy version |
Quality-guarded group; outside is an invariant breach |
X-Quality-Receipt |
Signed, unencrypted binding of organization, decision, model, profile, policy and serving conditions | With quality routing when the key belongs to an organization; cite in /v1/quality/assessments |
X-Quality-Audit |
selected; lane=audit; p=<rate> |
Response selected before its outcome; missing labels leave the sealed cohort incomplete |
X-Quality-Cascade |
primary_accepted; stages=1; check=format or escalated_accepted; stages=2; check=format |
Every released answer in an enabled cascade group |
check=format establishes a format check, not semantic correctness. An unverified cascade refuses with 502 quality_cascade_unverified. See quality-guarded routing and its bounded cascade.