Errors
Read type to decide what to do, code to know why, param to know where, and message to know what to change. Only 503 and 500 are ever 5xx; nothing is billed on an error, with the two exceptions on Retries and billing outcomes.
| Status | Type | What to do |
|---|---|---|
| 400 | invalid_request_error | Fix the request. Never retry it unchanged. The message names the field, the model, the limit and the count. |
| 401 | authentication_error | Check HIPS_API_KEY and the Authorization: Bearer header. The message never says whether a key is unknown or revoked. |
| 402 | insufficient_credit | Top up, or wait for the free allowance to reset; the message names when. Out of credit, auto_reload says whether the workspace's auto reload is adding credit (on: retry after a minute) or not (capped, failed, off), and on a paid plan pool_refreshes_at says when the next weekly pool of included credit starts; Billing has both. |
| 403 | permission_error, workspace_suspended | The key's kind, the plan, the pool or the workspace's state refuses the request; the message names the Console screen that resolves it. |
| 404 | not_found_error | The id, the route or the result does not exist for this key. Never retry unchanged. |
| 429 | rate_limit_error | Wait Retry-After seconds, then retry. Nothing was charged. |
| 503 | overloaded_error | Wait Retry-After seconds, then retry; or, for pool_unavailable, enable fallback if your data-use and region rules allow it. Nothing was charged. |
| 500 | api_error | Retry once. Nothing was charged. Quote the x-hips-request-id to support. |
- Status
- 400
- Type
invalid_request_error- What to do
- Fix the request. Never retry it unchanged. The message names the field, the model, the limit and the count.
- Status
- 401
- Type
authentication_error- What to do
- Check
HIPS_API_KEYand theAuthorization: Bearerheader. The message never says whether a key is unknown or revoked.
- Status
- 402
- Type
insufficient_credit- What to do
- Top up, or wait for the free allowance to reset; the message names when. Out of credit,
auto_reloadsays whether the workspace's auto reload is adding credit (on: retry after a minute) or not (capped,failed,off), and on a paid planpool_refreshes_atsays when the next weekly pool of included credit starts; Billing has both.
- Status
- 403
- Type
permission_error,workspace_suspended- What to do
- The key's kind, the plan, the pool or the workspace's state refuses the request; the message names the Console screen that resolves it.
- Status
- 404
- Type
not_found_error- What to do
- The id, the route or the result does not exist for this key. Never retry unchanged.
- Status
- 429
- Type
rate_limit_error- What to do
- Wait
Retry-Afterseconds, then retry. Nothing was charged.
- Status
- 503
- Type
overloaded_error- What to do
- Wait
Retry-Afterseconds, then retry; or, forpool_unavailable, enable fallback if your data-use and region rules allow it. Nothing was charged.
- Status
- 500
- Type
api_error- What to do
- Retry once. Nothing was charged. Quote the
x-hips-request-idto support.
invalid_json: The body is not JSON, or not an object. Retry: No.missing_required_parameter: A required field or header is absent;paramnames it. Retry: No.invalid_type: A field has the wrong JSON type. Retry: No.invalid_value: 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.unknown_parameter: A field the gateway does not know, at any depth;paramnames it. Retry: No.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;paramnames it andmessagenames the model. Retry: No.unsupported_value:nother than 1,stream_optionswithoutstream, a message role, part, item or tool type not accepted, a hosted tool that is not served. Retry: No.stateful_not_supported: State HIPS does not keep:storeandmetadataon chat completions;store: true,previous_response_id,conversation,metadata,background: trueanditem_referenceon Responses. Retry: No.type_not_served: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.context_length_exceeded: The prompt is over the model'scontext_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.max_tokens_exceeded:max_tokens(on Responsesmax_output_tokens) over the model'smax_output_tokens. Retry: No.invalid_image: An image part or input cannot be decoded, is of an unsupported type or over the pixel limit. Retry: No.request_too_large,input_too_large,too_many_inputs,upload_too_large: A limit of the Limits page. Retry: No.input_too_long: OnPOST /v1/rerank, a query or a document over 32 KiB of text, refused whole and never cut. Retry: No.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. Retry: No; send fewer or shorter inputs.task_mismatch:taskis not the model's task, or the model is not an embedding model or a reranker on its route. Retry: No.use_jobs: A task type that runs only as an asynchronous job (video_generation); the job routes are not built yet. Retry: No.not_a_language_model: A task model named on an OpenAI-compatible route. Retry: No.deployment_stopped: Thedep_is instopped; start it in the Console. Retry: No.upload_not_found,upload_expired,upload_incomplete,upload_mismatch,upload_consumed,upload_purpose_mismatch,upload_region_mismatch: Anupload_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).invalid_requirement: A requirement header or field with an unknown value. Retry: No.requirement_conflict: Two requirements that cannot both hold, a header and ahipsfield 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.stable_price_not_in_force:pricing_mode: stablewith no stable price covering this workspace, model and period. Retry: No.invalid_idempotency_key,idempotency_key_reused,idempotency_in_progress: The idempotency rules. Retry: The last one, later.request_timeout: The body stopped arriving. Retry: Yes.router_no_candidate: 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.guardrail_blocked: A content moderation guardrail withblockfound 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.guardrail_input_too_long: A content moderation guardrail withblockcannot check all of the request's text;paramismessages. Retry: No.content_refused: 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.image_withheld: Not a request's answer: the error a withheld image carries in a task'sresultsor in an image route'ships.withheld, beside the images delivered, its message the statement of reasons. A withheld image is not charged. Retry: No.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. Retry: No.knowledge_not_available: A Knowledge route while Knowledge's prices are not in effect. Knowledge is not switched on in production yet. Retry: No.limit_reached: A file or knowledge base past a limit the message names. Knowledge is not switched on in production yet. Retry: No.region_unavailable: A knowledge base in a region whose store does not exist yet. Knowledge is not switched on in production yet. Retry: No.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, oneurlor 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.storage_marked_for_deletion: OnPOST /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).
missing_api_key: NoAuthorizationheader, or not a bearer (on Messages, nox-api-keyeither). Retry: No.invalid_api_key: Unknown, malformed or revoked key or person's token; on Messages,x-api-keyandAuthorizationcarrying different values. The message never says which. Retry: No.token_expired: A person's access token past its life; the tool refreshes it and sends the request again. Retry: After the refresh.insufficient_credit: The balance does not cover the request's maximum cost at the bound quote. Retry: After a top-up.budget_exceeded: A budget guardrail of the workspace, the key or the person is at its limit withblock; the error carriesguardrailandresets_at(nullfor a budget that never resets). Never a payment challenge. Retry: Afterresets_at, or once the limit is raised.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 thanfullwriting a knowledge base's documents. Retry: No.insufficient_scope: A person's access token without theinferencescope. Retry: No; sign the tool in with the scope.region_not_on_plan: A region requirement on a plan without region selection. Retry: No.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 (todaygemma-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.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. Retry: No.model_not_allowed,region_not_allowed: A model, or a region requirement, that an access guardrail keeps out, the guardrail named in the error'sguardrailmember. Retry: No.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. Retry: No.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. Retry: After verification.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. Retry: After verification.account_restricted: 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.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. Retry: After resolution.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. Retry: After about a minute.workspace_deleted: The workspace is deleted (restorable 30 days). Retry: After restore.
model_not_found: Unknown catalog id, alias, pinned id ordep_; another workspace'sdep_; a name starting withhips-routerthat is not one of the four routers. Retry: No.upload_not_found,file_not_found,batch_not_found: An id in the path, orinput_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.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. Retry: No.result_expired: A task, embeddings or rerank request retried with itsidempotency-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.route_not_found: Unknown path, among them every/v1/jobspath (not built) and Knowledge's paths while Knowledge is switched off. Retry: No.route_not_available: A route that is built and not offered on this gateway: uploads, files and batches in production, andPOST /v1/messages/count_tokens. Retry: No.method_not_allowed: A known path with another method;Allowis sent. Retry: No.
rate_limit_exceeded: A rate limit;paramisrequests,tokens,uploads,batches(batches created per hour) orknowledge_search;Retry-After. Retry: Yes, afterRetry-After.concurrency_limit_exceeded: Too many open batches;paramisbatches;Retry-After. Retry: Yes, afterRetry-After.
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. Retry: Yes, after the given delay.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. Retry: Yes, after the given delay.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, 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.pool_unavailable: 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.deployment_not_ready: Thedep_isallocatingorloading, or waits for its version's tariff (tariff_pending);Retry-After. Retry: Yes.overloaded: Eligible workers exist and every one is saturated, or the queue is full;Retry-After. Retry: Yes.guardrail_unavailable: A content moderation check withblockcould 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.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. Retry: Yes, afterRetry-After.internal_error: A fault in HIPS. Nothing billed. Retry: Once.attempt_failed: Every attempt failed for a reason that is not the client's and retries are exhausted. Nothing billed. Retry: Once.deadline_exceeded: The request's own time bound ended it;x-should-retry: false. Nothing billed. Retry: Not unchanged.
One data: line holding the error envelope, then the stream closes without [DONE]. OpenAI clients raise on it. The usage record shows the outcome. See Streaming.
/statusservedThe public status line, on https://ai.hips.com, with no key.
GET https://ai.hips.com/status answers the public status line as JSON, with no key: {"status", "components", "updated_at"}, as the platform writes it, held for 5 seconds (Cache-Control: public, max-age=5). Before any line is written, status is unknown, components empty and updated_at null: never a state made up. Read it beside a 503 to tell a wider incident from a busy model.
Related sheets
- Sheet
- 19 of 20
- Detail
- B
- Updated
- 2026-11-16