Errors and headers

Status codes, mifr_action values, and x-mifr-* verdict headers.

Errors use the OpenAI envelope plus code and mifr_action (the SDK ignores those extras). SSE uses the same object in data: {"error":…} and still omits [DONE]. An HTTP abort sends no body.

{
  "error": {
    "message": "…",
    "type": "api_error",
    "code": "provider_unavailable",
    "param": null,
    "mifr_action": "wait"
  }
}

mifr_action is one of retry, wait, fix_key, fix_request, or pick_model.

Status codes

HTTP	code	mifr_action	When
401	invalid_api_key	fix_key	Missing or wrong Bearer
400	invalid_request	fix_request	Bad JSON, missing model/messages, unsupported part, oversized messages
413	invalid_request	fix_request	Body over 1 MiB
405	invalid_request	fix_request	Method not allowed
404	invalid_request	fix_request	No such route
404	model_not_found	pick_model	No provider serving that model at the floor, or unknown alias
503	provider_unavailable	wait	None at the floor, or a named Mac offline / below floor
503	directory_unavailable	wait	Chat key lookup down
504	timeout	retry	Overall wait exceeded
502	trust_refused	wait	Log / MDA / pin after failover exhausted
502	receipt_failed	retry	Disputed receipt
502	provider_error	retry	Transport
502	stream_interrupted	retry	Post-token fail; new request, do not splice
502	directory_unavailable	wait	/v1/models or /v1/providers could not list

Unknown routes return 404. PUT / DELETE / TRACE return 405 with Allow: GET, POST, OPTIONS. If the caller hangs up, the gateway records aborted and sends no body.

Verdict headers

Successful non-stream completions put identity on HTTP headers. On a stream, the same facts appear on the terminal SSE chunk with snake_case names (- becomes _). They cannot ride on the SSE HTTP head, because that head is flushed before a provider is chosen.

Headers are the gateway’s report; mifr_receipt is the proof.

HTTP	SSE field	When
x-mifr-trust	x_mifr_trust	Always: granted rung (hardware / transparent / process)
x-mifr-provider	x_mifr_provider	Always: provider key id
x-mifr-model	x_mifr_model	Always: catalog alias served
x-mifr-attempts	x_mifr_attempts	Always: 1 means no hop
x-mifr-serial	x_mifr_serial	hardware: full Apple-attested serial
x-mifr-pick	x_mifr_pick	Omitted when pinned: idle / queue
x-mifr-chip	x_mifr_chip	Omitted when pinned: small / large / unknown
x-mifr-cdhash	x_mifr_cdhash	When the receipt carries a signed cdhash
x-mifr-log-index	x_mifr_log_index	When that cdhash is a logged build
x-mifr-posture-age	x_mifr_posture_age	hardware: SecurityInfo age in seconds
x-mifr-mid-hop	x_mifr_mid_hop	N1 died after a token and N2 finished
x-mifr-hedge	x_mifr_hedge	Pre-token idle-idle pair was dispatched (1)
x-mifr-e2e-ms	x_mifr_e2e_ms	Always on a finished call
x-mifr-ttft-ms	x_mifr_ttft_ms	Stream only: first content chunk
x-mifr-itl-ms	x_mifr_itl_ms	Stream only: mean gap between non-empty chunks
x-mifr-tok-s	x_mifr_tok_s	When receipt completion_tokens > 0
x-mifr-tok-s-kind	x_mifr_tok_s_kind	decode (stream) or e2e (non-stream)

OpenAI and Vercel SDKs ignore extra HTTP headers and extra JSON keys.

Routing

When you omit provider, the gateway picks idle-first near-tie. If the chosen Mac dies, hangs (90 seconds with no token), stalls (90 seconds since the last token), or returns a bad receipt, the gateway retries another qualified Mac: at most two pre-token failovers, plus one mid-stream hop after the first token. Two idle Macs may be raced before the first token (x-mifr-hedge: 1). It never retries the same id, never drops to a lower floor, and never returns an unverified completion. A pin does not hop or hedge.