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 a region requirement, and it is off by default. Underautoit changes nothing: Auto already takes any pool the request may use. - A pool in the model id: on chat completions, Responses and Messages,
modelmay end in:auto,:certifiedor:community, which isx-hips-poolnaming that pool, with fallback off for a pool;x-hips-poolnaming anything else beside it, orx-hips-fallback: truebeside a pool, is a 400requirement_conflict(A pool in the model id). - 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 serves every request in the Certified pool, at the Certified pool's rates for the model, the quote
x-hips-quotenames. - Its answer's
x-hips-poolreadscertified, andx-hips-modeland the answer'smodelname the model served. Thex-hips-gpu-*headers are sent only where they are known, so an answer in the Certified pool may carry none. - A parameter a model does not take is never stripped: the request is answered 400
unsupported_parameter, itsparamnaming it (Request parameters).
hips
{"hips": {"pool": "community", "pricing_mode": "market", "region": null, "fallback": false}}Besides Authorization: Bearer and the requirements above:
x-hips-pool, x-hips-pricing-mode, x-hips-region, x-hips-fallbackthe requirementsThe four request requirements on the OpenAI-compatible routes and on Messages, below.
idempotency-keystringOn
POST /v1/tasks,POST /v1/embeddings,POST /v1/rerank,POST /v1/images/generations,POST /v1/images/edits, and on uploads, files and batches where they are offered (Idempotency). Never on chat completions, Responses or Messages.x-api-keya key or a person's tokenOn
POST /v1/messagesalone, as Anthropic's clients send it: the same credential asAuthorization: Bearer. Both sent with different values is a 401invalid_api_key.anthropic-version2023-06-01Required on
POST /v1/messages: absent is a 400missing_required_parameter, another value a 400invalid_value.anthropic-betastringOn
POST /v1/messages, read as information and never refused: the body's fields decide what is asked for.
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). A fresh id per request: the gateway never takes a client's.
x-request-idreq_...The same id under the generic name the OpenAI SDKs read (their
_request_id), on every response of the gateway.x-hips-modelpinned idThe pinned id served; under a router, the model the router chose, never the router. 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-hips-gpu-model, x-hips-gpu-vendor, x-hips-gpu-backendstringsOn an answer a provider's GPU served (H132, decided 2026-11-09): the model of that GPU as its machine reported it, in its normal form; the vendor; and the backend its engine ran on. Each is sent where it is known;
x-hips-gpu-modelis left out while too few providers report that model. Never an id of the device, the GPU or the provider. Absent where the server that answered is no provider's GPU, so an answer in the Certified pool may carry none (Answers in the Certified pool).x-hips-router<router>; preference=<value>; ...On an answer a router chose the model for: the router's name, then
;-separated members,preference,sourceandreadalways,reason,task,difficulty,floorandtrieswhere they apply. The answer'ships.routerobject carries the same.x-hips-guardrailsgrd_...;<action>, comma-separatedOn an answer a content moderation guardrail acted on with
flagorredact: each guardrail's id and its action,;unavailableafter one whose check could not run. Never a matched value.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 the language-model routes.
x-ratelimit-limit-uploads, x-ratelimit-remaining-uploads, x-ratelimit-reset-uploadsinteger, integer, secondsOn
POST /v1/uploadsand its 429, under the workspace's daily cap on uploads: the cap, what remains, and the seconds until the oldest upload of the window leaves it (86394s).idempotent-replayedtrueOn an answer replayed for an
idempotency-key(uploads, files, batches), with the original'sx-hips-request-id.x-should-retryfalseOn a 500
deadline_exceeded: the request's own time bound ended it, so an SDK does not send it again unchanged.Server-Timingkb-base,kb-embed,kb-searchOn a Knowledge search, the time of each stage. Knowledge is not switched on in production yet.
openai-poll-after-msintegerOn a Knowledge base or document still being read: when to read it again, as OpenAI's SDKs poll. Knowledge is not switched on in production yet.
AllowmethodsOn a 404
method_not_allowed: the methods the path takes (POST, orGET, HEAD, DELETE).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), and the same id is sent as x-request-id, the name the OpenAI SDKs read. It is the id of a chat completion and of a Responses and Messages answer, 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: an id a client sends under either name is ignored and a fresh one is made.
Related sheets
- Sheet
- 18 of 20
- Detail
- R
- Updated
- 2026-11-16