Requirements and headers

Pool, pricing mode, region and fallback are requirements of a request. The scheduler enforces them on every attempt; the gateway validates them and binds the quote under them.

• Precedence: a value in the request (header or hips field) beats the key's default; the key's default beats the platform default. On the task API both may be sent; when both are present and differ, a 400 requirement_conflict. The HIPS SDK sends the hips object and never the headers.
• Validation at the gateway: an unknown value is a 400 invalid_requirement. A region on a plan without region selection is a 403 region_not_on_plan. stable without a stable price in force is a 400 stable_price_not_in_force. A conflict the catalog decides statically is a 400 requirement_conflict.
• Enforcement at the scheduler: whether eligible supply exists now is not the gateway's to know for certain; pool_unavailable and no_capacity are 503s from the scheduler's answer. Never silently cross a required boundary to make a request succeed.
• Fallback never weakens a rule: fallback: true lets the scheduler place a job in the other pool when the named pool has nothing eligible; it never relaxes region or the request-data policy, and it is off by default.
• Requirements travel with the job: stored at acceptance, applied to every attempt and every retry; the requirements object on a job and the x-hips-pool, x-hips-pricing-mode and x-hips-region response headers show the effective ones.
• The lane is not a requirement: a dep_ on an allocation is always_on; everything else is shared. x-hips-lane reports it.

On the OpenAI clients a requirement rides as a header: default_headers on the Python client, defaultHeaders on the Node client, -H on cURL.

00000000000000000000000000000000000000001{"hips": {"pool": "personal", "pricing_mode": "market", "region": null, "fallback": false}}

On every response, errors included unless the rule says otherwise. The x-hips-* values are also what the usage record stores, so a client that logs the headers can reconcile against the Console line by line.

x-hips-request-id: req_<base32> is on every response, every error, every stream head and every idempotent replay (the original's). It is the id of a chat completion, it is carried to the worker and onto every attempt, it is the usage record's key, and the Console's Usage and activity view searches by it. A support question quotes it. HIPS does not accept a client-chosen request id; whether the gateway also sends x-request-id is open Not decided yet.