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.
| Requirement | Header (OpenAI-compatible routes) | `hips` body field (task API) | Values | Default when the key has none |
|---|---|---|---|---|
| Pool | x-hips-pool | pool | auto, community, certified (the former personal and approved are still taken, the same pools) | auto: the platform's default, and a key's unless it names a pool |
| Pricing mode | x-hips-pricing-mode | pricing_mode | market, stable | market |
| Region | x-hips-region | region | A coarse code Not decided yet, or absent | Absent (no region constraint) |
| Fallback | x-hips-fallback | fallback | true, false | false |
- Requirement
- Pool
- Header (OpenAI-compatible routes)
x-hips-pool- `hips` body field (task API)
pool- Values
auto,community,certified(the formerpersonalandapprovedare still taken, the same pools)- Default when the key has none
auto: the platform's default, and a key's unless it names a pool
- Requirement
- Pricing mode
- Header (OpenAI-compatible routes)
x-hips-pricing-mode- `hips` body field (task API)
pricing_mode- Values
market,stable- Default when the key has none
market
- Requirement
- Region
- Header (OpenAI-compatible routes)
x-hips-region- `hips` body field (task API)
region- Values
- A coarse code Not decided yet, or absent
- Default when the key has none
- Absent (no region constraint)
- Requirement
- Fallback
- Header (OpenAI-compatible routes)
x-hips-fallback- `hips` body field (task API)
fallback- Values
true,false- Default when the key has none
false
- Precedence: a value in the request (header or
hipsfield) 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 400requirement_conflict. The HIPS SDK sends thehipsobject 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 403region_not_on_plan.stablewithout a stable price in force is a 400stable_price_not_in_force. A conflict the catalog decides statically is a 400requirement_conflict. - Enforcement at the scheduler: whether eligible supply exists now is not the gateway's to know for certain;
pool_unavailableandno_capacityare 503s from the scheduler's answer. Never silently cross a required boundary to make a request succeed. - Auto: a request whose pool is
auto, named or by default, runs in one pool the scheduler chooses for it at acceptance, among the pools the workspace allows that offer and price the model and have eligible supply for it now under every other requirement. It takes the lowest balanced score of the request's expected charge in the pool and the expected time to first token there, ties to the lower price and then to the Certified pool; where a pool has no estimate of the first token, price alone decides. The pool chosen serves every attempt and retry of the job and prices it:x-hips-poolandx-hips-quotename that pool and its quote. - Fallback never weakens a rule:
fallback: truelets 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. Underautoit changes nothing: Auto already takes any pool the request may use. - Requirements travel with the job: stored at acceptance, applied to every attempt and every retry; the
requirementsobject on a job and thex-hips-pool,x-hips-pricing-modeandx-hips-regionresponse headers show the effective ones. - The lane is not a requirement: a
dep_on an allocation isalways_on; everything else isshared.x-hips-lanereports 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.
hips
{"hips": {"pool": "community", "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-idreq_...On every response, every error, every stream head and every idempotent replay (the original's).
x-hips-modelpinned idThe pinned id served. Not on errors before resolution.
x-hips-deploymentdep_...The deployment id, when the request named one.
x-hips-poolcommunityorcertifiedThe pool that ran the work, never
auto: underautothe pool the scheduler chose. When fallback was used, or the request ran underauto, this is how a client sees it. Not on errors before placement.x-hips-lanesharedoralways_onFollows from what the request names: a
dep_on an allocation isalways_on; everything else isshared.x-hips-pricing-modemarketorstableThe effective pricing mode.
x-hips-regionregion codeThe effective region code, or absent.
x-hips-quotequote_...oroffer_...The quote bound at acceptance; on a
stablerequest, the stable-price offer in force. Whether it also carries the bound rates is open Not decided yet.x-hips-cost-microsintegerThe charge in USD micro-dollars. Not on streamed responses (the
hipsobject of the final usage chunk instead) and not on errors (nothing charged).x-hips-latency-msintegerFrom the gateway's receipt of the complete request to the complete answer. On a streamed response, in the
hipsobject.x-ratelimit-limit-requests, x-ratelimit-remaining-requests, x-ratelimit-reset-requestsinteger, integer, durationThe key's request limit in the current window, what remains, and the time to reset in OpenAI's duration format, so clients that read them keep working.
x-ratelimit-limit-tokens, x-ratelimit-remaining-tokens, x-ratelimit-reset-tokensinteger, integer, durationThe same for tokens on language-model routes; on the task API the unit is task units with the same header names.
Retry-AftersecondsOn 429 and 503, nothing else.
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.
Related sheets
- Sheet
- 11 of 13
- Detail
- I
- Updated
- 2026-10-21
- Status
- Preview