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. The one exception is POST /v1/messages and the paths under it, which answer the same statuses and codes in Anthropic's shape. 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. A guardrail's refusals add a guardrail member beside code (id, name, and for a content check check and pattern), and budget_exceeded adds resets_at. Out of credit, insufficient_credit adds auto_reload, and on a paid plan pool_refreshes_at, when the next weekly pool of included credit starts (Billing).
model_not_on_plan adds two members beside code: feature, what the plan does not include (model, router, knowledge or deployments on these routes; guardrails too in the Console), and required_plan, the lowest plan whose terms include it (free, pro or business), or null where no plan offered now does. Both are read from the plans' terms, which HIPS may change with notice, never from a list in the gateway. A model or feature HIPS has added to the workspace itself counts as part of its plan until the date that addition ends. The message names the workspace's plan, what it includes, and Billing in the Console, where an owner or admin chooses a plan. The Messages route keeps both members. A workspace whose plan has no terms in force is never refused this way.
A refusal by plan
{"error": {"message": "The model `<id>` is not on the Free plan, which includes ... The Pro plan includes it: an owner or admin chooses a plan in the Console's Billing.", "type": "permission_error", "param": null, "code": "model_not_on_plan", "feature": "model", "required_plan": "pro"}}Below a feature's plan a workspace keeps what it made. Its guardrails keep enforcing and cannot be changed; its Knowledge bases are kept, read and deleted, nothing added; its deployments are kept and answer model_not_on_plan until it is on a plan with deployments, an always-on deployment stopped with its capacity released and its charges ended, and its owners and admins told; a batch accepted on a paid plan runs to its end. Being a provider never needs a plan.
Messages error
{"type": "error", "error": {"type": "invalid_request_error", "message": "<message>", "code": "<code>"}, "request_id": "req_..."}The statuses and codes are the same; type is Anthropic's for the status: 402 is billing_error, both 403 types are permission_error, and 503 stays 503 with overloaded_error (Anthropic's 529 is not used). code is the code of the table below, an extension Anthropic's clients ignore.
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
Every code the gateway answers, read from its code on 2026-11-11. A code of a route that is not live in production says so. 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. A batch's validation codes and its lines' codes are on the Batch jobs page.
| 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 | type_not_served | POST /v1/audio/transcriptions or /v1/audio/speech, or POST /v1/images/generations or /v1/images/edits while no model of the route's type is served: the message names the type | Once the type is 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, 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 | 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 | 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 |
| 400 | invalid_request_error | use_jobs | A task type that runs only as an asynchronous job (video_generation); the job routes are not built yet | No |
| 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 |
| 400 | invalid_request_error | upload_not_found, upload_expired, upload_incomplete, upload_mismatch, upload_consumed, upload_purpose_mismatch, upload_region_mismatch | An upload_id that is unknown or another workspace's, past expires_at, without bytes, with bytes that differ from the declaration, already consumed, of another purpose than the request needs, or stored in another region than the request's region requirement. Uploads are not offered in production yet | 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, community with an always-on deployment, a knowledge base whose requirements the request cannot meet | 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 | 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 |
| 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 |
| 400 | invalid_request_error | guardrail_input_too_long | A content moderation guardrail with block cannot check all of the request's text; param is messages | No |
| 400 | invalid_request_error | content_refused | An image request the content checks refused: its prompt or an input image asks for content the Acceptable Use Policy prohibits (param the prompt, inputs[0].text, for a generation, inputs for an edit; before any work), or every image made was withheld (param task). The message is the statement of reasons. Nothing charged | No |
| 400 | invalid_request_error | image_withheld | Not a request's answer: the error a withheld image carries in a task's results or in an image route's hips.withheld, beside the images delivered, its message the statement of reasons. A withheld image is not charged | No |
| 400 | invalid_request_error | tool_not_available | A hosted tool whose price per call is not published, so it is not offered yet. Knowledge is not switched on in production yet | No |
| 400 | invalid_request_error | knowledge_not_available | A Knowledge route while Knowledge's prices are not in effect. Knowledge is not switched on in production yet | No |
| 400 | invalid_request_error | limit_reached | A file or knowledge base past a limit the message names. Knowledge is not switched on in production yet | No |
| 400 | invalid_request_error | region_unavailable | A knowledge base in a region whose store does not exist yet. Knowledge is not switched on in production yet | No |
| 400 | invalid_request_error | file_too_large, invalid_file_format, batch_not_offered | A batch input file over 200 MB; one that is not UTF-8 JSON Lines of objects, is empty, holds more than 50,000 lines, or names more than one model, one url or a router (the message names the first line at fault); a batch of a model sold without batch. Batches and files are not offered in production yet | No |
| 400 | invalid_request_error | storage_marked_for_deletion | On POST /v1/vector_stores, POST /v1/vector_stores/{vector_store_id}/files and POST /v1/vector_stores/{vector_store_id}/file_batches: the workspace's stored files are marked for deletion, since a month's storage could not be paid, and nothing new is added to them; the message names the date. Reading and deleting still work. Knowledge is not switched on in production yet | Once credit brings the balance back to zero or above, which clears the mark at once (the Console answers the same code as a 409) |
| 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 |
| 401 | authentication_error | token_expired | A person's access token past its life; the tool refreshes it and sends the request again | After the refresh |
| 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 | key_scope_denied | The key's kind excludes the route: a retrieval key on any route but its batch and file reads; a key other than full writing a knowledge base's documents | No |
| 403 | permission_error | insufficient_scope | A person's access token without the inference scope | No; sign the tool in with the scope |
| 403 | permission_error | region_not_on_plan | A region requirement on a plan without region selection | 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 |
| 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 |
| 403 | permission_error | guardrail_unsupported | A content moderation guardrail applies to text it does not scan yet: a batch, or a task request with text; the guardrail named, uncharged | No |
| 403 | permission_error | workspace_unverified | The workspace's owner has not passed identity verification; the message names the Console's verification screen. Not sent while identity verification is switched off, as it is since 2026-11-09; documented for when it is switched back on | After verification |
| 403 | permission_error | member_unverified | A person's access token whose person has not passed identity verification. Not sent while identity verification is switched off, as it is since 2026-11-09; documented for when it is switched back on | After verification |
| 403 | permission_error | account_restricted | The workspace's owner, or the person a token belongs to, cannot use HIPS. The message says to contact HIPS support | No; contact support |
| 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 where to resolve it | After resolution |
| 403 | workspace_suspended | plan_lapsed | A lapse no longer pauses a workspace: a lapsed or canceled paid plan, or an ended plan grant, moves it to the free plan at once. Only a workspace a lapse paused before then answers this, until the platform moves it to the free plan within about a minute | After about a minute |
| 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_; a name starting with hips-router that is not one of the four routers | No |
| 404 | not_found_error | upload_not_found, file_not_found, batch_not_found | An id in the path, or input_file_id, that is unknown, deleted, expired, another workspace's, or out of the credential's reach. Batches and files are not offered in production yet | No |
| 404 | not_found_error | knowledge_base_not_found | A knowledge base that is not the workspace's, or that is being deleted. Knowledge is not switched on in production yet | No |
| 404 | not_found_error | result_expired | A task, embeddings or rerank request retried with its idempotency-key after the first completed: no answer is kept, and the message names the first request's req_ id. It ran and was billed once | No |
| 404 | not_found_error | route_not_found | Unknown path, among them every /v1/jobs path (not built) and Knowledge's paths while Knowledge is switched off | No |
| 404 | not_found_error | route_not_available | A route that is built and not offered on this gateway: uploads, files and batches in production, and POST /v1/messages/count_tokens | 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, uploads, batches (batches created per hour) or knowledge_search; Retry-After | Yes, after Retry-After |
| 429 | rate_limit_error | concurrency_limit_exceeded | Too many open batches; param is batches; 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 | model_loading | Every GPU that holds the model would have to load it first, and none could give a first token within the request's bound now, so the request is not sent to one; HIPS's placement brings the model up for the requests that follow; Retry-After. Nothing is charged | Yes, after the given delay |
| 503 | overloaded_error | context_size_not_measured | The prompt fits a window a GPU can hold, in a size not measured on it yet (never tried there, or being measured); Retry-After, and the largest size that works now in the message, as context_length_exceeded names it. A size the GPUs keep failing to read in time is the 400 context_length_exceeded instead, since a retry would not succeed. A prompt's size is never answered no_capacity | Yes, or send a shorter prompt |
| 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 |
| 503 | overloaded_error | guardrail_unavailable | A content moderation check with block could not run in time, or is one a decision service judges on a request that requires a region (Guardrails); Retry-After; uncharged | Yes, unless the request requires a region |
| 503 | overloaded_error | content_check_unavailable | The content checks of an image request could not run (the decision service failed or did not answer in time), and HIPS sends no image request unchecked; Retry-After; uncharged | Yes, after Retry-After |
| 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 |
| 500 | api_error | deadline_exceeded | The request's own time bound ended it; x-should-retry: false. Nothing billed | Not unchanged |
- 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
type_not_served- Situation
POST /v1/audio/transcriptionsor/v1/audio/speech, orPOST /v1/images/generationsor/v1/images/editswhile no model of the route's type is served: the message names the type- Retry
- Once the type is served
- 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
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
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
taskis not the model's task, or the model is not an embedding model or a reranker on its route- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
use_jobs- Situation
- A task type that runs only as an asynchronous job (
video_generation); the job routes are not built yet - Retry
- No
- 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
- 400
- Type
invalid_request_error- Code
upload_not_found,upload_expired,upload_incomplete,upload_mismatch,upload_consumed,upload_purpose_mismatch,upload_region_mismatch- Situation
- An
upload_idthat is unknown or another workspace's, pastexpires_at, without bytes, with bytes that differ from the declaration, already consumed, of another purpose than the request needs, or stored in another region than the request's region requirement. Uploads are not offered in production yet - 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,communitywith an always-on deployment, a knowledge base whose requirements the request cannot meet - 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
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
- 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
- 400
- Type
invalid_request_error- Code
guardrail_input_too_long- Situation
- A content moderation guardrail with
blockcannot check all of the request's text;paramismessages - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
content_refused- Situation
- An image request the content checks refused: its prompt or an input image asks for content the Acceptable Use Policy prohibits (
paramthe prompt,inputs[0].text, for a generation,inputsfor an edit; before any work), or every image made was withheld (paramtask). The message is the statement of reasons. Nothing charged - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
image_withheld- Situation
- Not a request's answer: the error a withheld image carries in a task's
resultsor in an image route'ships.withheld, beside the images delivered, its message the statement of reasons. A withheld image is not charged - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
tool_not_available- Situation
- A hosted tool whose price per call is not published, so it is not offered yet. Knowledge is not switched on in production yet
- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
knowledge_not_available- Situation
- A Knowledge route while Knowledge's prices are not in effect. Knowledge is not switched on in production yet
- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
limit_reached- Situation
- A file or knowledge base past a limit the message names. Knowledge is not switched on in production yet
- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
region_unavailable- Situation
- A knowledge base in a region whose store does not exist yet. Knowledge is not switched on in production yet
- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
file_too_large,invalid_file_format,batch_not_offered- Situation
- A batch input file over 200 MB; one that is not UTF-8 JSON Lines of objects, is empty, holds more than 50,000 lines, or names more than one model, one
urlor a router (the message names the first line at fault); a batch of a model sold without batch. Batches and files are not offered in production yet - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
storage_marked_for_deletion- Situation
- On
POST /v1/vector_stores,POST /v1/vector_stores/{vector_store_id}/filesandPOST /v1/vector_stores/{vector_store_id}/file_batches: the workspace's stored files are marked for deletion, since a month's storage could not be paid, and nothing new is added to them; the message names the date. Reading and deleting still work. Knowledge is not switched on in production yet - Retry
- Once credit brings the balance back to zero or above, which clears the mark at once (the Console answers the same code as a 409)
- Status
- 401
- Type
authentication_error- Code
missing_api_key- Situation
- No
Authorizationheader, or not a bearer (on Messages, nox-api-keyeither) - 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-keyandAuthorizationcarrying different values. The message never says which - Retry
- No
- Status
- 401
- Type
authentication_error- Code
token_expired- Situation
- A person's access token past its life; the tool refreshes it and sends the request again
- Retry
- After the refresh
- 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
key_scope_denied- Situation
- The key's kind excludes the route: a retrieval key on any route but its batch and file reads; a key other than
fullwriting a knowledge base's documents - Retry
- No
- Status
- 403
- Type
permission_error- Code
insufficient_scope- Situation
- A person's access token without the
inferencescope - Retry
- No; sign the tool in with the scope
- 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
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
- 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
- 403
- Type
permission_error- Code
guardrail_unsupported- Situation
- A content moderation guardrail applies to text it does not scan yet: a batch, or a task request with text; the guardrail named, uncharged
- 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. Not sent while identity verification is switched off, as it is since 2026-11-09; documented for when it is switched back on
- Retry
- After verification
- Status
- 403
- Type
permission_error- Code
member_unverified- Situation
- A person's access token whose person has not passed identity verification. Not sent while identity verification is switched off, as it is since 2026-11-09; documented for when it is switched back on
- Retry
- After verification
- Status
- 403
- Type
permission_error- Code
account_restricted- Situation
- The workspace's owner, or the person a token belongs to, cannot use HIPS. The message says to contact HIPS support
- Retry
- No; contact support
- 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 where to resolve it
- Retry
- After resolution
- Status
- 403
- Type
workspace_suspended- Code
plan_lapsed- Situation
- A lapse no longer pauses a workspace: a lapsed or canceled paid plan, or an ended plan grant, moves it to the free plan at once. Only a workspace a lapse paused before then answers this, until the platform moves it to the free plan within about a minute
- Retry
- After about a minute
- 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_; a name starting withhips-routerthat is not one of the four routers - Retry
- No
- Status
- 404
- Type
not_found_error- Code
upload_not_found,file_not_found,batch_not_found- Situation
- An id in the path, or
input_file_id, that is unknown, deleted, expired, another workspace's, or out of the credential's reach. Batches and files are not offered in production yet - Retry
- No
- Status
- 404
- Type
not_found_error- Code
knowledge_base_not_found- Situation
- A knowledge base that is not the workspace's, or that is being deleted. Knowledge is not switched on in production yet
- Retry
- No
- Status
- 404
- Type
not_found_error- Code
result_expired- Situation
- A task, embeddings or rerank request retried with its
idempotency-keyafter the first completed: no answer is kept, and the message names the first request'sreq_id. It ran and was billed once - Retry
- No
- Status
- 404
- Type
not_found_error- Code
route_not_found- Situation
- Unknown path, among them every
/v1/jobspath (not built) and Knowledge's paths while Knowledge is switched off - Retry
- No
- Status
- 404
- Type
not_found_error- Code
route_not_available- Situation
- A route that is built and not offered on this gateway: uploads, files and batches in production, and
POST /v1/messages/count_tokens - 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,uploads,batches(batches created per hour) orknowledge_search;Retry-After - Retry
- Yes, after
Retry-After
- Status
- 429
- Type
rate_limit_error- Code
concurrency_limit_exceeded- Situation
- Too many open batches;
paramisbatches;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
model_loading- Situation
- Every GPU that holds the model would have to load it first, and none could give a first token within the request's bound now, so the request is not sent to one; HIPS's placement brings the model up for the requests that follow;
Retry-After. Nothing is charged - Retry
- Yes, after the given delay
- Status
- 503
- Type
overloaded_error- Code
context_size_not_measured- Situation
- The prompt fits a window a GPU can hold, in a size not measured on it yet (never tried there, or being measured);
Retry-After, and the largest size that works now in the message, ascontext_length_exceedednames it. A size the GPUs keep failing to read in time is the 400context_length_exceededinstead, since a retry would not succeed. A prompt's size is never answeredno_capacity - Retry
- Yes, or send a shorter prompt
- 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
- 503
- Type
overloaded_error- Code
guardrail_unavailable- Situation
- A content moderation check with
blockcould not run in time, or is one a decision service judges on a request that requires a region (Guardrails);Retry-After; uncharged - Retry
- Yes, unless the request requires a region
- Status
- 503
- Type
overloaded_error- Code
content_check_unavailable- Situation
- The content checks of an image request could not run (the decision service failed or did not answer in time), and HIPS sends no image request unchecked;
Retry-After; uncharged - Retry
- Yes, after
Retry-After
- 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
- Status
- 500
- Type
api_error- Code
deadline_exceeded- Situation
- The request's own time bound ended it;
x-should-retry: false. Nothing billed - Retry
- Not unchanged
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
- 18 of 20
- Detail
- S
- Updated
- 2026-11-16