Messages

Anthropic's Messages API, served so that Anthropic's clients and Claude Code run on HIPS's catalog models (decided 2026-10-29). A claude-* id is unknown on HIPS and answered so, never mapped to another model. The request is served by the chat completions route's own path, so the key, the requirement headers, the limits, the quote, placement and the response headers are those of chat completions; a field the route does not take is a 400 in Anthropic's wording.

POST/v1/messagesserved

Anthropic's Messages API, with x-api-key and anthropic-version: 2023-06-01, in Anthropic's error shape.

Fig. 1, sheet 17API reference

00000000000000000000000000000000000000001# HIPS_BASE_URL is https://ai.hips.com/v12curl "$HIPS_BASE_URL/messages" \3  -H "x-api-key: $HIPS_API_KEY" \4  -H "anthropic-version: 2023-06-01" \5  -H "Content-Type: application/json" \6  -d "{\"model\":\"$HIPS_MODEL\",\"max_tokens\":256,\"messages\":[{\"role\":\"user\",\"content\":\"Explain GPU inference in two sentences.\"}]}"

Reads from the environmentHIPS_BASE_URLHIPS_API_KEYHIPS_MODEL

Headers

Parts list: Request headers

x-api-keyAccepted
A workspace API key or a person's access token, as Anthropic's clients send it, on this route alone. Authorization: Bearer works too; both sent with different values is a 401 invalid_api_key, and neither is a 401 missing_api_key. An inference_only key and a token with the inference scope reach the route.
anthropic-versionRequired
2023-06-01. Absent is a 400 missing_required_parameter with Anthropic's wording, anthropic-version: header is required; another value is a 400 invalid_value naming the one served.
anthropic-betaRead, never refused
The body's fields decide what is asked for: each field a beta adds is accepted or refused by the rules below.
x-hips-pool, x-hips-pricing-mode, x-hips-region, x-hips-fallbackAccepted
The requirements, as on chat completions. A person's token takes the workspace's tool defaults.

A query string on the path (Claude Code sends ?beta=true) is ignored. The answer carries the response headers of chat completions, and on a whole answer x-hips-cost-micros and x-hips-latency-ms.

The request

Parts list: Fields

modelRequired
A catalog id, an alias, a pinned id or a router name; unknown is a 404 not_found_error naming the model.
max_tokensRequired
A positive integer, the output cap. Over the model's max_output_tokens it is a 400 in Anthropic's wording: max_tokens: <asked> > <maximum>, which is the maximum allowed number of output tokens for <model>.
messagesRequired, non-empty
Roles user and assistant, in the content blocks below; the last message is a user message. A system role is a 400: messages: Unexpected role "system". The allowed roles are "user" or "assistant". Use the top-level system parameter for the initial system prompt.
systemAccepted
A string, or an array of text blocks.
streamAccepted
true streams the events below; absent or false answers whole.
temperature, top_pAccepted
Numbers from 0 to 1, Anthropic's range.
stop_sequencesAccepted
At most 16 strings (decided 2026-11-01); more is a 400 invalid_value, stop_sequences: List should have at most 16 items.
toolsAccepted
Client tools (name, description, input_schema, cache_control, type: "custom"), on a model that advertises tools in the pool the request resolves to. A name matches ^[a-zA-Z0-9_-]{1,128}$. A server tool, and a field a beta adds to a tool (defer_loading, strict, input_examples, allowed_callers, eager_input_streaming), is a 400 tools.<n>.<field>: Extra inputs are not permitted.
tool_choiceAccepted
auto, any, tool with its name, or none; disable_parallel_tool_use: true asks for at most one call.
thinkingAccepted, ignored
adaptive, enabled (with budget_tokens) and disabled are accepted and change nothing (decided 2026-11-01): no thinking block is returned.
metadatauser_id accepted, discarded
Never stored, logged or sent to a worker. Any other member is a 400.
cache_controlAccepted where Anthropic places it
{"type": "ephemeral"} on system blocks, content blocks and tools, as satisfied. A ttl is a 400: HIPS promises no cache lifetime.
top_k, context_management, output_config, output_format, safeguards, service_tier, container, mcp_servers, speed, inference_geoRejected, 400 unsupported_parameter
In Anthropic's wording, <name>: Extra inputs are not permitted, a nested field named by its path.
Any other nameRejected, 400 unknown_parameter
In the same wording.

Content block	In	Rule
A string `content`, `text`	`user`, `assistant`	Text; `citations` is a 400
`image`	`user`	A `base64` source of `image/jpeg`, `image/png`, `image/gif` or `image/webp`, on a model that advertises `vision`. A `url` source is a 400 `invalid_value`: HIPS never fetches an image address
`tool_use`	`assistant`	A call the model made earlier, replayed
`tool_result`	`user`	The result of a call, a string or `text` and `image` blocks; `is_error` is accepted
`thinking`, `redacted_thinking`, `document`, `search_result`, `server_tool_use` and any other `type`		A 400 naming the block's `type`

The answer

Parts list: The message object

id
The request id, req_..., as x-hips-request-id.
model
The pinned id served, as x-hips-model; under a router, the model it chose.
content
A text block with the model's text, when it wrote any, then one tool_use block per call (id, name, input). Arguments that are not JSON are given as a JSON string, never repaired.
stop_reason, stop_sequence
tool_use, max_tokens, stop_sequence with the sequence where the engine names it, else end_turn. pause_turn and refusal are never sent.
usage
input_tokens (the input not read from a cache), cache_read_input_tokens (the cached tokens billed, 0 today), cache_creation_input_tokens (always 0), output_tokens.

Streaming

stream: true answers 200 with text/event-stream, each event as event: <type> and one data: line, 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. A ping event goes out while nothing else has been sent for the keep-alive interval. message_delta carries the cumulative usage and the hips object (cost_micros, latency_ms, quote), which Anthropic's clients ignore. A failure after the stream started is one event: error with the error object below, attempt_failed when the worker stopped, and the stream closes without message_stop; nothing is billed for it.

Streamed events

00000000000000000000000000000000000000001event: message_start2data: {"type":"message_start","message":{"id":"req_...","type":"message","role":"assistant","model":"<pinned id>","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":0,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":0}}}3 4event: content_block_start5data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}6 7event: content_block_delta8data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"..."}}9 10event: content_block_stop11data: {"type":"content_block_stop","index":0}12 13event: message_delta14data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":0,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":0},"hips":{"cost_micros":0,"latency_ms":0,"quote":"quote_..."}}15 16event: message_stop17data: {"type":"message_stop"}

Streamed events sample

Errors

Every refusal on this route and the paths under it, the gateway's own included, is in Anthropic's shape, with the statuses and codes of the Errors page; code is an extension Anthropic's clients ignore, and request_id is x-hips-request-id.

Error

00000000000000000000000000000000000000001{2  "type": "error",3  "error": {4    "type": "invalid_request_error",5    "message": "anthropic-version: header is required",6    "code": "missing_required_parameter"7  },8  "request_id": "req_..."9}

Error sample

Status	`type` on this route
400	`invalid_request_error`
401	`authentication_error`
402	`billing_error`
403	`permission_error`
404	`not_found_error`
429	`rate_limit_error`, with `retry-after` in whole seconds
503	`overloaded_error`, with status 503: Anthropic's 529 is not used
500	`api_error`

A prompt longer than the model's context is worded as Anthropic words it, so a client compacts the conversation or lowers max_tokens: prompt is too long: <prompt> tokens > <context> maximum, or input length and max_tokens exceed context limit: <prompt> + <max_tokens> > <context>, decrease input length or max_tokens and try again. The prompt is never truncated.

What is not served

Route	Answer
`POST /v1/messages/count_tokens`	404 `route_not_available` (Count tokens)
`POST /v1/messages/batches` and its routes, Anthropic's Files and Models APIs	404 `route_not_found`; models are listed by `GET /v1/models` in OpenAI's shape

Status	Type	Code	Situation	Retry
400	`invalid_request_error`	`missing_required_parameter`	A required field or header is absent; `param` names it	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`	`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`	`max_tokens_exceeded`	`max_tokens` (on Responses `max_output_tokens`) over the model's `max_output_tokens`	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
401	`authentication_error`	`missing_api_key`	No `Authorization` header, or not a bearer (on Messages, no `x-api-key` either)	No
401	`authentication_error`	`invalid_api_key`	Unknown, malformed or revoked key or person's token; on Messages, `x-api-key` and `Authorization` carrying different values. The message never says which	No
402	`billing_error`	`insufficient_credit`	The balance does not cover the request's maximum cost at the bound quote	After a top-up
402	`billing_error`	`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
missing_required_parameter
Situation
A required field or header is absent; param names it
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
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
max_tokens_exceeded
Situation
max_tokens (on Responses max_output_tokens) over the model's max_output_tokens
Retry
No
Status
400
Type
invalid_request_error
Code
guardrail_blocked
Situation
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
Retry
No
Status
401
Type
authentication_error
Code
missing_api_key
Situation
No Authorization header, or not a bearer (on Messages, no x-api-key either)
Retry
No
Status
401
Type
authentication_error
Code
invalid_api_key
Situation
Unknown, malformed or revoked key or person's token; on Messages, x-api-key and Authorization carrying different values. The message never says which
Retry
No
Status
402
Type
billing_error
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
billing_error
Code
budget_exceeded
Situation
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
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 guardrail member
Retry
No
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
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

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

1# HIPS_BASE_URL is https://ai.hips.com/v12curl "$HIPS_BASE_URL/messages" \3 -H "x-api-key: $HIPS_API_KEY" \4 -H "anthropic-version: 2023-06-01" \5 -H "Content-Type: application/json" \6 -d "{\"model\":\"$HIPS_MODEL\",\"max_tokens\":256,\"messages\":[{\"role\":\"user\",\"content\":\"Explain GPU inference in two sentences.\"}]}"

Content block

Rule

A string content, text

user, assistant

Text; citations is a 400

image

user

A base64 source of image/jpeg, image/png, image/gif or image/webp, on a model that advertises vision. A url source is a 400 invalid_value: HIPS never fetches an image address

tool_use

assistant

A call the model made earlier, replayed

tool_result

user

The result of a call, a string or text and image blocks; is_error is accepted

thinking, redacted_thinking, document, search_result, server_tool_use and any other type

A 400 naming the block's type

1event: message_start2data: {"type":"message_start","message":{"id":"req_...","type":"message","role":"assistant","model":"<pinned id>","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":0,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":0}}}3 4event: content_block_start5data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}6 7event: content_block_delta8data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"..."}}9 10event: content_block_stop11data: {"type":"content_block_stop","index":0}12 13event: message_delta14data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":0,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":0},"hips":{"cost_micros":0,"latency_ms":0,"quote":"quote_..."}}15 16event: message_stop17data: {"type":"message_stop"}

1{2 "type": "error",3 "error": {4 "type": "invalid_request_error",5 "message": "anthropic-version: header is required",6 "code": "missing_required_parameter"7 },8 "request_id": "req_..."9}

Status

`type` on this route

400

invalid_request_error

401

authentication_error

402

billing_error

403

permission_error

404

not_found_error

429

rate_limit_error, with retry-after in whole seconds

503

overloaded_error, with status 503: Anthropic's 529 is not used

500

api_error

Route

Answer

POST /v1/messages/count_tokens

404 route_not_available (Count tokens)

POST /v1/messages/batches and its routes, Anthropic's Files and Models APIs

404 route_not_found; models are listed by `GET /v1/models` in OpenAI's shape

Status

Type

Code

Situation

Retry

400

invalid_request_error

missing_required_parameter

A required field or header is absent; param names it

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

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

max_tokens_exceeded

max_tokens (on Responses max_output_tokens) over the model's max_output_tokens

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

401

authentication_error

missing_api_key

No Authorization header, or not a bearer (on Messages, no x-api-key either)

401

authentication_error

invalid_api_key

Unknown, malformed or revoked key or person's token; on Messages, x-api-key and Authorization carrying different values. The message never says which

402

billing_error

insufficient_credit

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

After a top-up

402

billing_error

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

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

500

api_error

attempt_failed

Every attempt failed for a reason that is not the client's and retries are exhausted. Nothing billed

Once

Headers

The request

The answer

Streaming

Errors

Related sheets

Headers

The request

The answer

Streaming

Errors

Related sheets