Embeddings and rerank

Two front doors on the task API (decided 2026-11-04): an embedding request in OpenAI's shape and a rerank request in Cohere's, each served as the task it stands for, embedding or rerank, with the task route's key, limits, idempotency-key, requirement headers, quote and placement. Neither body takes a hips object: requirements ride as the x-hips-* headers. A model answers once an embedding model or a reranker is published and priced in the catalog.

POST/v1/embeddingsserved

Embeddings in OpenAI's shape, billed per started second of compute. A model answers once an embedding model is published and priced.

Fig. 1, sheet 17API reference

00000000000000000000000000000000000000001{"model": "<catalog id>", "input": ["First text.", "Second text."], "encoding_format": "float"}

Language

Parts list: Embeddings fields

modelRequired
A non-empty string: a catalog id, alias or pinned id of an embedding model. A model of another task is a 400 task_mismatch; a router is a 400 invalid_value.
inputRequired
A string, or an array of 1 to 2,048 strings, none empty; more is a 400 too_many_inputs. Token-id arrays are a 400 unsupported_value: HIPS takes text, tokenized with the model's own tokenizer.
encoding_formatAccepted
float (the default) or base64, each vector's little-endian 32-bit floats; anything else is a 400 unsupported_value.
dimensionsAccepted
A whole number above 0: the model's own dimension, or fewer on a model whose entry says it may be cut (limits.truncatable); otherwise a 400 unsupported_value naming the model's dimension.
userAccepted, not used
A string.
Any other nameRejected, 400 unknown_parameter
Never ignored.

The vectors come in input order, each of the model's own dimension, unit length, cut to dimensions and made unit length again when fewer are asked. usage.prompt_tokens is the gateway's own count with the model's tokenizer: a figure, never the bill.

POST/v1/rerankserved

Rerank in Cohere's shape, billed per started second of compute. A model answers once a reranker is published and priced.

00000000000000000000000000000000000000001{"model": "<catalog id>", "query": "Which document is about GPUs?", "documents": ["a", "b", {"text": "c"}], "top_n": 2, "return_documents": true}

Language

Parts list: Rerank fields

modelRequired
A reranker.
queryRequired
A non-empty string of at most 32 KiB.
documentsRequired
1 to 1,000 strings or {"text"} objects (Cohere's two shapes), each non-empty and at most 32 KiB; more documents is a 400 too_many_inputs, a longer one a 400 input_too_long.
top_nAccepted
From 1 to the number of documents; every document when absent. More than the documents sent is a 400 invalid_value.
return_documentsAccepted
true puts each document's text in its result; false by default.
max_tokens_per_docRejected, 400 unsupported_parameter
HIPS never cuts a document.
Any other nameRejected, 400 unknown_parameter
Never ignored.

Scores are the reranker's relevance through the logistic function, from 0 to 1, the most relevant first, equal scores in input order. Every document is scored, whatever top_n returns.

Billing

Both routes bill per started second of the request's compute time, at least one second (H109, decided 2026-11-05: models other than language models bill per started second, never per token). The time is the gateway's own measure of the attempts that completed the request, each held to its expected time at its GPU's typical speed, never a device's report. The rerank answer names the seconds in meta.billed_units.seconds; the embeddings answer keeps OpenAI's token counts, and the cost is in x-hips-cost-micros.

Never cut

An input, a document or a query longer than the model reads at once is refused whole before any work, never cut and never billed: a 400 context_length_exceeded at its field, naming its tokens and the model's bound, counted with the model's own tokenizer. An input too large for one attempt is a 400 input_too_large. A request the measured speed of every GPU serving the model shows cannot finish within its time limit is a 400 exceeds_time_limit.

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`	`context_length_exceeded`	The prompt is over the model's `context_length`, or over the largest window any GPU serves it at now, that limit and the prompt's count in the message; 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`	`request_too_large`, `input_too_large`, `too_many_inputs`, `upload_too_large`	A limit of the Limits page	No
400	`invalid_request_error`	`input_too_long`	On `POST /v1/rerank`, a query or a document over 32 KiB of text, refused whole and never cut	No
400	`invalid_request_error`	`exceeds_time_limit`	An embedding or rerank request that the measured speed of every GPU serving the model shows cannot finish within its time limit; the message says how long it would take. Sent before any work, uncharged	No; send fewer or shorter inputs
400	`invalid_request_error`	`task_mismatch`	`task` is not the model's task, or the model is not an embedding model or a reranker on its route	No
402	`insufficient_credit`	`insufficient_credit`	The balance does not cover the request's maximum cost at the bound quote	After a top-up
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

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; param names 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: 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
Retry
No
Status
400
Type
invalid_request_error
Code
unknown_parameter
Situation
A field the gateway does not know, at any depth; param names 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; param names it and message names the model
Retry
No
Status
400
Type
invalid_request_error
Code
unsupported_value
Situation
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
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, that limit and the prompt's count in the message; 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
request_too_large, input_too_large, too_many_inputs, upload_too_large
Situation
A limit of the Limits page
Retry
No
Status
400
Type
invalid_request_error
Code
input_too_long
Situation
On POST /v1/rerank, a query or a document over 32 KiB of text, refused whole and never cut
Retry
No
Status
400
Type
invalid_request_error
Code
exceeds_time_limit
Situation
An embedding or rerank request that the measured speed of every GPU serving the model shows cannot finish within its time limit; the message says how long it would take. Sent before any work, uncharged
Retry
No; send fewer or shorter inputs
Status
400
Type
invalid_request_error
Code
task_mismatch
Situation
task is not the model's task, or the model is not an embedding model or a reranker on its route
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
404
Type
not_found_error
Code
model_not_found
Situation
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
Retry
No
Status
429
Type
rate_limit_error
Code
rate_limit_exceeded
Situation
A rate limit; param is requests, tokens, uploads, batches (batches created per hour) or knowledge_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

Sheet: 17 of 19
Detail: H
Updated: 2026-11-11

Status

Type

Code

Situation

Retry

400

invalid_request_error

invalid_json

The body is not JSON, or not an object

400

invalid_request_error

missing_required_parameter

A required field or header is absent; param names it

400

invalid_request_error

invalid_type

A field has the wrong JSON type

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

400

invalid_request_error

unknown_parameter

A field the gateway does not know, at any depth; param names it

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

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

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, that limit and the prompt's count in the message; the prompt is never truncated. On embeddings and rerank, an input longer than the model reads at once, never cut

400

invalid_request_error

request_too_large, input_too_large, too_many_inputs, upload_too_large

A limit of the Limits page

400

invalid_request_error

input_too_long

On POST /v1/rerank, a query or a document over 32 KiB of text, refused whole and never cut

400

invalid_request_error

exceeds_time_limit

An embedding or rerank request that the measured speed of every GPU serving the model shows cannot finish within its time limit; the message says how long it would take. Sent before any work, uncharged

No; send fewer or shorter inputs

400

invalid_request_error

task_mismatch

task is not the model's task, or the model is not an embedding model or a reranker on its route

402

insufficient_credit

The balance does not cover the request's maximum cost at the bound quote

After a top-up

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

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

Billing

Never cut

Related sheets

Billing

Never cut

Related sheets