Errors
One envelope on every public route, including unknown paths and the responses the edge answers when it can, in the OpenAI shape so compatible clients parse it. Only 503 and 500 are ever 5xx. Nothing is billed on an error.
Envelope
{ "error": { "message": "<a sentence a developer can act on>", "type": "<type>", "param": "<field or header, or null>", "code": "<code>" }}The message is for a developer: it names the field, the model, the limit and the count, and never a provider, a device, an address or another workspace. param names the field or header, or is null. Every error carries x-hips-request-id.
The type list is closed; a specific situation is a code under one of these types.
| Status | Type | Meaning |
|---|---|---|
| 400 | invalid_request_error | The request cannot be served as sent; nothing is billed |
| 401 | authentication_error | No key, or a key the gateway does not accept |
| 402 | insufficient_credit | The balance does not cover the request's maximum cost at the bound quote |
| 403 | permission_error, workspace_suspended | The key, plan or workspace may not do this |
| 404 | not_found_error | A model, job, upload or route that does not exist for this key |
| 429 | rate_limit_error | A limit of the key or workspace; Retry-After is sent |
| 503 | overloaded_error | No capacity under the request's requirements; Retry-After is sent |
| 500 | api_error | A fault in HIPS; nothing is billed |
- Status
- 400
- Type
invalid_request_error- Meaning
- The request cannot be served as sent; nothing is billed
- Status
- 401
- Type
authentication_error- Meaning
- No key, or a key the gateway does not accept
- Status
- 402
- Type
insufficient_credit- Meaning
- The balance does not cover the request's maximum cost at the bound quote
- Status
- 403
- Type
permission_error,workspace_suspended- Meaning
- The key, plan or workspace may not do this
- Status
- 404
- Type
not_found_error- Meaning
- A model, job, upload or route that does not exist for this key
- Status
- 429
- Type
rate_limit_error- Meaning
- A limit of the key or workspace;
Retry-Afteris sent
- Status
- 503
- Type
overloaded_error- Meaning
- No capacity under the request's requirements;
Retry-Afteris sent
- Status
- 500
- Type
api_error- Meaning
- A fault in HIPS; nothing is billed
The complete list for this version. A request either succeeds or fails as a whole, except a task's per-input errors and a stream that fails after it started. A limit is never a 5xx, so SDKs that retry every 5xx do not retry a 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 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 | 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 OpenAI field HIPS does not accept, or a feature the named model does not advertise | No |
| 400 | invalid_request_error | unsupported_value | n other than 1, stream_options without stream, a message role or part type not accepted | No |
| 400 | invalid_request_error | stateful_not_supported | store, metadata, previous_response_id, conversation | No |
| 400 | invalid_request_error | context_length_exceeded | The prompt is over the model's context_length; the prompt is never truncated | No |
| 400 | invalid_request_error | max_tokens_exceeded | max_tokens over the model's max_output_tokens | No |
| 400 | invalid_request_error | invalid_image | An image part or input cannot be decoded, is of an unsupported type or over the pixel limit | 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 | task_mismatch | task is not the model's task | No |
| 400 | invalid_request_error | not_a_language_model | A task model or a task-model deployment named on an OpenAI-compatible route | No |
| 400 | invalid_request_error | deployment_stopped | The dep_ is in stopped; start it in the Console | No |
| 400 | invalid_request_error | upload_not_found, upload_expired, upload_incomplete, upload_mismatch, upload_consumed | An upload_id that is unknown or another workspace's, past expires_at, without bytes, with bytes that differ from the declaration, or already consumed | No (upload_incomplete: after the PUT) |
| 400 | invalid_request_error | invalid_requirement | A requirement header or field with an unknown value | No |
| 400 | invalid_request_error | requirement_conflict | Two requirements that cannot both hold, a header and a hips field that differ, a pool the model is never offered in, personal with an always-on deployment | No |
| 400 | invalid_request_error | stable_price_not_in_force | pricing_mode: stable with no stable price covering this workspace, model and period | No |
| 400 | invalid_request_error | use_jobs | A synchronous task the gateway can tell will exceed the synchronous limit | As a job |
| 400 | invalid_request_error | invalid_idempotency_key, idempotency_key_reused, idempotency_in_progress | The idempotency rules | The last one, later |
| 400 | invalid_request_error | request_timeout | The body stopped arriving | Yes |
| 401 | authentication_error | missing_api_key | No Authorization header, or not a bearer | No |
| 401 | authentication_error | invalid_api_key | Unknown, malformed or revoked key. The message never says which | No |
| 402 | insufficient_credit | insufficient_credit | The balance does not cover the request's maximum cost at the bound quote. On the free plan with the allowance used, the message names when it resets | After a top-up |
| 403 | permission_error | key_scope_denied | The key's kind excludes the route | No |
| 403 | permission_error | model_not_on_plan | The model or feature is not in the workspace's plan | No |
| 403 | permission_error | region_not_on_plan | A region requirement on a plan without region selection | No |
| 403 | permission_error | pool_not_allowed | A pool the workspace may not use for this model | No |
| 403 | permission_error | workspace_unverified | The workspace's owner has not passed identity verification; the message names the Console's verification screen | After verification |
| 403 | workspace_suspended | workspace_paused | The workspace is paused: by balance, by an administrator, by a dispute, by a budget hard stop or by an owner. The message says which and where to resolve it | After resolution |
| 403 | workspace_suspended | plan_lapsed | The subscription lapsed and no owner has yet acknowledged the free plan's request-data policy or paid; the policies hold meanwhile | After acknowledgment or payment |
| 403 | workspace_suspended | workspace_deleted | The workspace is deleted (restorable 30 days) | After restore |
| 404 | not_found_error | model_not_found | Unknown catalog id, alias, pinned id or dep_; another workspace's dep_ | No |
| 404 | not_found_error | job_not_found, upload_not_found | An id in the path that is unknown or another workspace's | No |
| 404 | not_found_error | result_expired | A job's result read after expires_at | No |
| 404 | not_found_error | route_not_found | Unknown path | No |
| 404 | not_found_error | route_not_available | A route of this contract not yet served (/v1/responses before validation) | No |
| 404 | not_found_error | method_not_allowed | A known path with another method; Allow is sent | No |
| 429 | rate_limit_error | rate_limit_exceeded | A rate limit; param is requests, tokens, units or uploads; Retry-After | Yes, after Retry-After |
| 429 | rate_limit_error | concurrency_limit_exceeded | Too many concurrent streams or active jobs; param is streams or jobs; 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 | Yes |
| 503 | overloaded_error | pool_unavailable | The named pool has no eligible supply for this model now and fallback is off; the other pool may have; Retry-After | Yes, or with fallback |
| 503 | overloaded_error | deployment_not_ready | The dep_ is allocating or loading, or waits for its version's tariff (tariff_pending); Retry-After | Yes |
| 503 | overloaded_error | overloaded | Eligible workers exist and every one is saturated, or the queue is full; Retry-After | Yes |
| 500 | api_error | internal_error | A fault in HIPS. Nothing billed | Once |
| 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 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
- 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 OpenAI field HIPS does not accept, or a feature the named model does not advertise
- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
unsupported_value- Situation
nother than 1,stream_optionswithoutstream, a message role or part type not accepted- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
stateful_not_supported- Situation
store,metadata,previous_response_id,conversation- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
context_length_exceeded- Situation
- The prompt is over the model's
context_length; the prompt is never truncated - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
max_tokens_exceeded- Situation
max_tokensover the model'smax_output_tokens- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
invalid_image- Situation
- An image part or input cannot be decoded, is of an unsupported type or over the pixel limit
- 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
task_mismatch- Situation
taskis not the model's task- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
not_a_language_model- Situation
- A task model or a task-model deployment 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
- 400
- Type
invalid_request_error- Code
upload_not_found,upload_expired,upload_incomplete,upload_mismatch,upload_consumed- Situation
- An
upload_idthat is unknown or another workspace's, pastexpires_at, without bytes, with bytes that differ from the declaration, or already consumed - Retry
- No (
upload_incomplete: after the PUT)
- Status
- 400
- Type
invalid_request_error- Code
invalid_requirement- Situation
- A requirement header or field with an unknown value
- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
requirement_conflict- Situation
- Two requirements that cannot both hold, a header and a
hipsfield that differ, a pool the model is never offered in,personalwith an always-on deployment - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
stable_price_not_in_force- Situation
pricing_mode: stablewith no stable price covering this workspace, model and period- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
use_jobs- Situation
- A synchronous task the gateway can tell will exceed the synchronous limit
- Retry
- As a job
- Status
- 400
- Type
invalid_request_error- Code
invalid_idempotency_key,idempotency_key_reused,idempotency_in_progress- Situation
- The idempotency rules
- Retry
- The last one, later
- Status
- 400
- Type
invalid_request_error- Code
request_timeout- Situation
- The body stopped arriving
- Retry
- Yes
- Status
- 401
- Type
authentication_error- Code
missing_api_key- Situation
- No
Authorizationheader, or not a bearer - Retry
- No
- Status
- 401
- Type
authentication_error- Code
invalid_api_key- Situation
- Unknown, malformed or revoked key. The message never says which
- 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. On the free plan with the allowance used, the message names when it resets
- Retry
- After a top-up
- Status
- 403
- Type
permission_error- Code
key_scope_denied- Situation
- The key's kind excludes the route
- Retry
- No
- Status
- 403
- Type
permission_error- Code
model_not_on_plan- Situation
- The model or feature is not in the workspace's plan
- Retry
- No
- Status
- 403
- Type
permission_error- Code
region_not_on_plan- Situation
- A region requirement on a plan without region selection
- Retry
- No
- Status
- 403
- Type
permission_error- Code
pool_not_allowed- Situation
- A pool the workspace may not use for this model
- Retry
- No
- Status
- 403
- Type
permission_error- Code
workspace_unverified- Situation
- The workspace's owner has not passed identity verification; the message names the Console's verification screen
- Retry
- After verification
- Status
- 403
- Type
workspace_suspended- Code
workspace_paused- Situation
- The workspace is paused: by balance, by an administrator, by a dispute, by a budget hard stop or by an owner. The message says which and where to resolve it
- Retry
- After resolution
- Status
- 403
- Type
workspace_suspended- Code
plan_lapsed- Situation
- The subscription lapsed and no owner has yet acknowledged the free plan's request-data policy or paid; the policies hold meanwhile
- Retry
- After acknowledgment or payment
- Status
- 403
- Type
workspace_suspended- Code
workspace_deleted- Situation
- The workspace is deleted (restorable 30 days)
- Retry
- After restore
- Status
- 404
- Type
not_found_error- Code
model_not_found- Situation
- Unknown catalog id, alias, pinned id or
dep_; another workspace'sdep_ - Retry
- No
- Status
- 404
- Type
not_found_error- Code
job_not_found,upload_not_found- Situation
- An id in the path that is unknown or another workspace's
- Retry
- No
- Status
- 404
- Type
not_found_error- Code
result_expired- Situation
- A job's result read after
expires_at - Retry
- No
- Status
- 404
- Type
not_found_error- Code
route_not_found- Situation
- Unknown path
- Retry
- No
- Status
- 404
- Type
not_found_error- Code
route_not_available- Situation
- A route of this contract not yet served (
/v1/responsesbefore validation) - Retry
- No
- Status
- 404
- Type
not_found_error- Code
method_not_allowed- Situation
- A known path with another method;
Allowis sent - Retry
- No
- Status
- 429
- Type
rate_limit_error- Code
rate_limit_exceeded- Situation
- A rate limit;
paramisrequests,tokens,unitsoruploads;Retry-After - Retry
- Yes, after
Retry-After
- Status
- 429
- Type
rate_limit_error- Code
concurrency_limit_exceeded- Situation
- Too many concurrent streams or active jobs;
paramisstreamsorjobs;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 - Retry
- Yes
- Status
- 503
- Type
overloaded_error- Code
pool_unavailable- Situation
- The named pool has no eligible supply for this model now and fallback is off; the other pool may have;
Retry-After - Retry
- Yes, or with fallback
- 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
- 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
internal_error- Situation
- A fault in HIPS. Nothing billed
- Retry
- Once
- 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
Note
Statuses outside this list (409 for idempotency_in_progress, 413 for an oversize body, 408 for a stalled body) are mapped to 400 to honor the closed list as written; the conventional statuses are open Not decided yet.
Related sheets
- Sheet
- 11 of 13
- Detail
- J
- Updated
- 2026-10-21
- Status
- Preview