Responses
OpenAI's Responses API, served so that OpenAI's SDKs and Codex run on HIPS's catalog models (decided 2026-10-29). The route is stateless: HIPS stores no response, so every request carries its whole conversation in input. The key, the requirement headers, the limits and the response headers are those of chat completions, and a field the route does not take is a 400 that names it.
/v1/responsesservedOpenAI's Responses shape, stateless: HIPS stores no response, so every request carries its whole conversation.
{ "model": "<catalog id>", "instructions": "Answer in one sentence.", "input": [ {"role": "user", "content": [{"type": "input_text", "text": "What does a GPU do?"}]} ], "store": false}Parts list: Fields
modelRequiredA catalog id, an alias, a pinned id or a router name; unknown is a 404
model_not_found.inputRequiredA string, read as one
usermessage, or a non-empty list of the items below.instructionsAcceptedA string, the conversation's first system message.
streamAcceptedtruestreams the events below; absent orfalseanswers whole.storefalse acceptedHIPS stores no response:
falseand the field's absence are accepted, and both read asfalse;trueis a 400stateful_not_supported.includeOne value acceptedA list holding
reasoning.encrypted_content: every reasoning item then answersencrypted_content: null, its text in the clear. Any other value is a 400unsupported_value.toolsAcceptedFunction tools,
{"type": "function", "name", "description", "parameters", "strict"}, on a model that advertisestoolsin the pool the request resolves to; a name of 1 to 64 characters. Any othertypeis a 400unsupported_valueattools[<n>].type: HIPS runs no tool of its own on this route.tool_choiceAcceptedauto,none,requiredor{"type": "function", "name"}; any other form is a 400unsupported_value.parallel_tool_callsAcceptedAs on chat completions, a permission:
true(what Codex sends on every request) allows more than one call where the model advertisesparallel_tool_callsand is served asfalse, at most one call, where it does not, never refused for it;falseasks for at most one call.reasoningAcceptedeffortis sent to the engine and needs thereasoningfeature;summary(auto,concise,detailedornone) is accepted and writes nothing, since a model's reasoning comes back whole.textAcceptedformat:{"type": "text"}, orjson_objectandjson_schema(name,schema,strict,description) on a model advertising them.verbosityis a 400unsupported_parameter.max_output_tokensAcceptedThe output cap; over the model's
max_output_tokensit is a 400max_tokens_exceedednamingmax_output_tokens.temperature, top_pAcceptedPassed to the engine.
prompt_cache_keyAcceptedAs on chat completions.
truncationdisabled acceptedHIPS never truncates a prompt;
autois a 400unsupported_value.client_metadata, userAccepted, discardedNever stored, logged or sent to a worker.
backgroundfalse acceptedtrueis a 400stateful_not_supported: every request is answered in its own connection.previous_response_id, conversation, metadataRejected, 400 stateful_not_supportedEach names state HIPS does not keep.
prompt_cache_retention, prompt_cache_options, prompt_cache_breakpoint, service_tier, prompt, max_tool_calls, top_logprobs, stream_optionsRejected, 400 unsupported_parameterNo cache lifetime is promised, pools and pricing modes are headers, and the others are not carried on this route.
cache_salt, hips and any other nameRejected, 400 unknown_parameterAt every depth. Requirements ride as the
x-hips-*headers.
| Item | Rule |
|---|---|
message | Roles developer, system, user and assistant. content is a string or a list of parts: input_text in any role; input_image in a user message, inline as a data URI, on a model advertising vision; output_text in an assistant message. developer and system messages reach the model as system messages. id and status are accepted and read as nothing |
reasoning | An earlier answer's reasoning, replayed: its shape checked, not sent to the worker |
function_call | A call the model made earlier: call_id, name, arguments |
function_call_output | A call's result: output a string or a list of input_text and input_image parts |
item_reference | 400 stateful_not_supported: it names a stored item |
Any other type | 400 unsupported_value at input[<n>].type |
- Item
message- Rule
- Roles
developer,system,userandassistant.contentis a string or a list of parts:input_textin any role;input_imagein ausermessage, inline as a data URI, on a model advertisingvision;output_textin anassistantmessage.developerandsystemmessages reach the model as system messages.idandstatusare accepted and read as nothing
- Item
reasoning- Rule
- An earlier answer's reasoning, replayed: its shape checked, not sent to the worker
- Item
function_call- Rule
- A call the model made earlier:
call_id,name,arguments
- Item
function_call_output- Rule
- A call's result:
outputa string or a list ofinput_textandinput_imageparts
- Item
item_reference- Rule
- 400
stateful_not_supported: it names a stored item
- Item
- Any other
type - Rule
- 400
unsupported_valueatinput[<n>].type
Parts list: The response object
idThe request id,
req_..., asx-hips-request-id.status, incomplete_detailscompletedandnull;incompleteand{"reason": "max_output_tokens"}when the output cap ended the answer.modelThe pinned id served, as
x-hips-model.outputIn this order: a
reasoningitem when the engine returned reasoning text (summary: [],contentofreasoning_text,encrypted_content: null); amessageitem with the model's text; onefunction_callitem per call,argumentsthe model's JSON string as written, never repaired. Ids are made from the request id (rs_,msg_,fc_).usageinput_tokens(cached included),input_tokens_details.cached_tokens,output_tokens,output_tokens_details.reasoning_tokenswhere the engine counts them,total_tokens.storeAlways
false.
stream: true answers 200 with text/event-stream, each event as event: <type> and one data: line carrying its type and a sequence_number from 0, relayed as the engine writes it. Nothing is sent before a worker answers, so a refusal before the first byte is an ordinary status and body.
| Event | When |
|---|---|
response.created, response.in_progress | First: the response object with status: "in_progress", output: [] and usage: null |
response.output_item.added, response.output_item.done | Each item as it opens and once it is complete |
response.reasoning_text.delta, .done | A reasoning item's text, then whole |
response.content_part.added, response.output_text.delta, response.output_text.done, response.content_part.done | A message's text part |
response.function_call_arguments.delta, .done | A call's arguments, then whole |
response.completed | Last on every answer that ended, with every item, the usage and the hips object (cost_micros, latency_ms, quote). An answer the output cap ended is response.completed with status: "incomplete"; response.incomplete is never sent |
response.failed | A failure after the stream started: status: "failed", the items finished so far and error with code and message; the stream ends with it and nothing is billed |
- Event
response.created,response.in_progress- When
- First: the response object with
status: "in_progress",output: []andusage: null
- Event
response.output_item.added,response.output_item.done- When
- Each item as it opens and once it is complete
- Event
response.reasoning_text.delta,.done- When
- A reasoning item's text, then whole
- Event
response.content_part.added,response.output_text.delta,response.output_text.done,response.content_part.done- When
- A message's text part
- Event
response.function_call_arguments.delta,.done- When
- A call's arguments, then whole
- Event
response.completed- When
- Last on every answer that ended, with every item, the usage and the
hipsobject (cost_micros,latency_ms,quote). An answer the output cap ended isresponse.completedwithstatus: "incomplete";response.incompleteis never sent
- Event
response.failed- When
- A failure after the stream started:
status: "failed", the items finished so far anderrorwithcodeandmessage; the stream ends with it and nothing is billed
A comment line (: keep-alive) goes out while nothing else has been sent for the keep-alive interval. Closing the connection cancels the work on the worker.
Every refusal is in the error envelope, and param names the field as this route names it (max_output_tokens, text.format.type, input[2].content[0].image_url). One is answered otherwise: a prompt longer than the model's context is, on a streamed request, 200 with response.created, response.in_progress and response.failed carrying context_length_exceeded, the one way Codex reads a request as over its context; on a whole request it is a 400 context_length_exceeded at input. The prompt is never truncated.
What is not served
| Route | Answer |
|---|---|
GET, DELETE /v1/responses/{id}, POST /v1/responses/{id}/cancel, GET /v1/responses/{id}/input_items, POST /v1/responses/compact | 404 route_not_found: HIPS stores no response |
GET /v1/responses | 404 method_not_allowed with Allow: POST |
- Route
GET,DELETE /v1/responses/{id},POST /v1/responses/{id}/cancel,GET /v1/responses/{id}/input_items,POST /v1/responses/compact- Answer
- 404
route_not_found: HIPS stores no response
- Route
GET /v1/responses- Answer
- 404
method_not_allowedwithAllow: POST
| Status | Type | Code | Situation | Retry |
|---|---|---|---|---|
| 400 | invalid_request_error | invalid_json | The body is not JSON, or not an object | No |
| 400 | invalid_request_error | missing_required_parameter | A required field or header is absent; param names it | No |
| 400 | invalid_request_error | invalid_type | A field has the wrong JSON type | No |
| 400 | invalid_request_error | invalid_value | A value is out of range or malformed: stop with more than 16 entries, a prompt_cache_key over 512 characters, a string holding a lone surrogate escape, a router name with an empty or unknown suffix, both max_tokens names with different values | No |
| 400 | invalid_request_error | unknown_parameter | A field the gateway does not know, at any depth; param names it | No |
| 400 | invalid_request_error | unsupported_parameter | A known field HIPS does not accept, or a feature the named model does not advertise in the pool the request resolves to; param names it and message names the model | No |
| 400 | invalid_request_error | unsupported_value | n other than 1, stream_options without stream, a message role, part, item or tool type not accepted, a hosted tool that is not served | No |
| 400 | invalid_request_error | stateful_not_supported | State HIPS does not keep: store and metadata on chat completions; store: true, previous_response_id, conversation, metadata, background: true and item_reference on Responses | No |
| 400 | invalid_request_error | context_length_exceeded | The prompt is over the model's context_length, or over the largest window any GPU serves it at now, or held only in a size that the GPUs able to hold it keep failing to read within the time limit; that limit and the prompt's count in the message, the limit the largest size that works now for this request, never more than the pool's context_window on Models; the prompt is never truncated. On embeddings and rerank, an input longer than the model reads at once, never cut | No |
| 400 | invalid_request_error | max_tokens_exceeded | max_tokens (on Responses max_output_tokens) over the model's max_output_tokens | No |
| 400 | invalid_request_error | router_no_candidate | A router has no model it can choose for this request: none takes what the request carries (param the first field at fault) or none is allowed under its requirements (param the header); the message says why and what would serve it. Before any worker, uncharged | No |
| 400 | invalid_request_error | guardrail_blocked | A content moderation guardrail with block found prompt injection or a sensitive pattern; param names the message and the error's guardrail member names the guardrail, the check and the pattern's type, never the matched text. Before any model ran, uncharged | No |
| 402 | insufficient_credit | insufficient_credit | The balance does not cover the request's maximum cost at the bound quote | After a top-up |
| 402 | insufficient_credit | budget_exceeded | A budget guardrail of the workspace, the key or the person is at its limit with block; the error carries guardrail and resets_at (null for a budget that never resets). Never a payment challenge | After resets_at, or once the limit is raised |
| 403 | permission_error | model_not_allowed, region_not_allowed | A model, or a region requirement, that an access guardrail keeps out, the guardrail named in the error's guardrail member | No |
| 404 | not_found_error | model_not_found | Unknown catalog id, alias, pinned id or dep_; another workspace's dep_; a name starting with hips-router that is not one of the four routers | No |
| 429 | rate_limit_error | rate_limit_exceeded | A rate limit; param is requests, tokens, uploads, batches (batches created per hour) or knowledge_search; Retry-After | Yes, after Retry-After |
| 503 | overloaded_error | no_capacity | No eligible worker under the request's requirements, in any pool the requirements allow; Retry-After. The message says what those pools can do now: a GPU that fits the model takes it when free or loads it when asked, which can take minutes or longer; or nothing can serve it, and a retry sooner than the given delay gets the same answer | Yes, after the given delay |
| 503 | overloaded_error | overloaded | Eligible workers exist and every one is saturated, or the queue is full; Retry-After | Yes |
| 500 | api_error | attempt_failed | Every attempt failed for a reason that is not the client's and retries are exhausted. Nothing billed | Once |
- Status
- 400
- Type
invalid_request_error- Code
invalid_json- Situation
- The body is not JSON, or not an object
- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
missing_required_parameter- Situation
- A required field or header is absent;
paramnames it - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
invalid_type- Situation
- A field has the wrong JSON type
- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
invalid_value- Situation
- A value is out of range or malformed:
stopwith more than 16 entries, aprompt_cache_keyover 512 characters, a string holding a lone surrogate escape, a router name with an empty or unknown suffix, bothmax_tokensnames with different values - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
unknown_parameter- Situation
- A field the gateway does not know, at any depth;
paramnames it - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
unsupported_parameter- Situation
- A known field HIPS does not accept, or a feature the named model does not advertise in the pool the request resolves to;
paramnames it andmessagenames the model - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
unsupported_value- Situation
nother than 1,stream_optionswithoutstream, a message role, part, item or tool type not accepted, a hosted tool that is not served- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
stateful_not_supported- Situation
- State HIPS does not keep:
storeandmetadataon chat completions;store: true,previous_response_id,conversation,metadata,background: trueanditem_referenceon Responses - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
context_length_exceeded- Situation
- The prompt is over the model's
context_length, or over the largest window any GPU serves it at now, or held only in a size that the GPUs able to hold it keep failing to read within the time limit; that limit and the prompt's count in the message, the limit the largest size that works now for this request, never more than the pool'scontext_windowon Models; the prompt is never truncated. On embeddings and rerank, an input longer than the model reads at once, never cut - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
max_tokens_exceeded- Situation
max_tokens(on Responsesmax_output_tokens) over the model'smax_output_tokens- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
router_no_candidate- Situation
- A router has no model it can choose for this request: none takes what the request carries (
paramthe first field at fault) or none is allowed under its requirements (paramthe header); the message says why and what would serve it. Before any worker, uncharged - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
guardrail_blocked- Situation
- A content moderation guardrail with
blockfound prompt injection or a sensitive pattern;paramnames the message and the error'sguardrailmember names the guardrail, the check and the pattern's type, never the matched text. Before any model ran, uncharged - Retry
- No
- Status
- 402
- Type
insufficient_credit- Code
insufficient_credit- Situation
- The balance does not cover the request's maximum cost at the bound quote
- Retry
- After a top-up
- Status
- 402
- Type
insufficient_credit- Code
budget_exceeded- Situation
- A budget guardrail of the workspace, the key or the person is at its limit with
block; the error carriesguardrailandresets_at(nullfor a budget that never resets). Never a payment challenge - Retry
- After
resets_at, or once the limit is raised
- Status
- 403
- Type
permission_error- Code
model_not_allowed,region_not_allowed- Situation
- A model, or a region requirement, that an access guardrail keeps out, the guardrail named in the error's
guardrailmember - Retry
- No
- Status
- 404
- Type
not_found_error- Code
model_not_found- Situation
- Unknown catalog id, alias, pinned id or
dep_; another workspace'sdep_; a name starting withhips-routerthat is not one of the four routers - Retry
- No
- Status
- 429
- Type
rate_limit_error- Code
rate_limit_exceeded- Situation
- A rate limit;
paramisrequests,tokens,uploads,batches(batches created per hour) orknowledge_search;Retry-After - Retry
- Yes, after
Retry-After
- Status
- 503
- Type
overloaded_error- Code
no_capacity- Situation
- No eligible worker under the request's requirements, in any pool the requirements allow;
Retry-After. The message says what those pools can do now: a GPU that fits the model takes it when free or loads it when asked, which can take minutes or longer; or nothing can serve it, and a retry sooner than the given delay gets the same answer - Retry
- Yes, after the given delay
- Status
- 503
- Type
overloaded_error- Code
overloaded- Situation
- Eligible workers exist and every one is saturated, or the queue is full;
Retry-After - Retry
- Yes
- Status
- 500
- Type
api_error- Code
attempt_failed- Situation
- Every attempt failed for a reason that is not the client's and retries are exhausted. Nothing billed
- Retry
- Once
Related sheets
- Sheet
- 18 of 20
- Detail
- C
- Updated
- 2026-11-15