Deployments
A deployment (dep_) is a customer model version made runnable, or a catalog model pinned to an always-on allocation. It is created in the Console in the first version (a public route is open Not decided yet); the API reads it and addresses it.
| Model type | Field | Route |
|---|---|---|
| Customer-owned language model | model: "dep_..." | POST /v1/chat/completions: not served yet; the dep_ answers 404 model_not_found |
| Customer-owned model of any other type | deployment: "dep_..." | POST /v1/tasks |
| A catalog model pinned to an always-on allocation | model: "dep_..." | The model's route |
- Model type
- Customer-owned language model
- Field
model: "dep_..."- Route
POST /v1/chat/completions: not served yet; thedep_answers 404model_not_found
- Model type
- Customer-owned model of any other type
- Field
deployment: "dep_..."- Route
POST /v1/tasks
- Model type
- A catalog model pinned to an always-on allocation
- Field
model: "dep_..."- Route
- The model's route
A dep_ in model on the task API is a 400 invalid_value that points at deployment; a task-model deployment named on an OpenAI-compatible route is a 400 not_a_language_model.
GET /v1/models lists no deployment yet: a deployment's state is read in the Console, and a request naming it answers by its state as below.
Parts list: The deployment object
deployment.stateallocating,loading,ready,busy,degraded,stopped, ortariff_pendingEvery transition is timestamped and explained in the Console. Allocation is not readiness. A
shareddeployment created before its version's tariff waits intariff_pending: it takes no request, a request naming it answers 503deployment_not_ready, and nothing is charged.deployment.modelThe customer model version (
mdl_and its version) or the catalog pinned id.deployment.lanesharedoralways_onalways_onexists in thecertifiedpool only.deployment.poolcommunityorcertifiedCustomer-owned models run in the
certifiedpool only at launch.deployment.sinceWhen the current state was entered.
The deployment's pool came with disclosed access conditions and fallback is set on the deployment: a request header or hips field may turn fallback off but never on; fallback: true on such a request is a 400 requirement_conflict. x-hips-deployment on the response carries the dep_ id; x-hips-lane reports the lane.
Deploying own models needs a plan that includes it, Business today: on any other plan a request naming the workspace's dep_ answers 403 model_not_on_plan with feature: "deployments" before its state is read, and the deployment is kept and answers again once the workspace is on such a plan. An always-on deployment of a workspace that drops below it is stopped by the platform, its capacity released and its charges ended, and its owners and admins are told; an owner starts it again once the plan is back.
| Status | Type | Code | Situation | Retry |
|---|---|---|---|---|
| 400 | invalid_request_error | not_a_language_model | A task model named on an OpenAI-compatible route | No |
| 400 | invalid_request_error | deployment_stopped | The dep_ is in stopped; start it in the Console | No |
| 403 | permission_error | model_not_on_plan | A model or feature the workspace's plan does not include, read from the plan's terms: on Free a model outside the Free plan's models (today gemma-4-e4b-it-8b, gpt-oss-120b, gpt-oss-20b and qwen3-14b), a router or Knowledge; on Free and Pro a deployment (dep_). The error adds feature and required_plan, the lowest plan that includes it. Answered before any placement, uncharged. A deployment refused this way is kept and answers again once the workspace is on a plan with deployments | After an owner or admin chooses a plan that includes it |
| 403 | permission_error | pool_not_allowed | A pool the workspace may not use for this model: one an access guardrail keeps out (named in the error), or a customer model's pool whose runtime-access conditions were not accepted | 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 |
| 503 | overloaded_error | deployment_not_ready | The dep_ is allocating or loading, or waits for its version's tariff (tariff_pending); Retry-After | Yes |
- Status
- 400
- Type
invalid_request_error- Code
not_a_language_model- Situation
- A task model named on an OpenAI-compatible route
- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
deployment_stopped- Situation
- The
dep_is instopped; start it in the Console - Retry
- No
- Status
- 403
- Type
permission_error- Code
model_not_on_plan- Situation
- A model or feature the workspace's plan does not include, read from the plan's terms: on Free a model outside the Free plan's models (today
gemma-4-e4b-it-8b,gpt-oss-120b,gpt-oss-20bandqwen3-14b), a router or Knowledge; on Free and Pro a deployment (dep_). The error addsfeatureandrequired_plan, the lowest plan that includes it. Answered before any placement, uncharged. A deployment refused this way is kept and answers again once the workspace is on a plan with deployments - Retry
- After an owner or admin chooses a plan that includes it
- Status
- 403
- Type
permission_error- Code
pool_not_allowed- Situation
- A pool the workspace may not use for this model: one an access guardrail keeps out (named in the error), or a customer model's pool whose runtime-access conditions were not accepted
- 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
- 503
- Type
overloaded_error- Code
deployment_not_ready- Situation
- The
dep_isallocatingorloading, or waits for its version's tariff (tariff_pending);Retry-After - Retry
- Yes
Related sheets
- Sheet
- 18 of 20
- Detail
- Q
- Updated
- 2026-11-12