Skip to content
HIPS
  • Earn with your GPU
  • Pricing
  • Docs
Sign inJoin early access
⌘K

Get started

  1. 01Developer hub
  2. 02Quickstart
  3. 03Migrate to HIPS

Guides

  1. 04HIPS SDK
  2. 05Import and run your model
  3. 06Model and task guides
    1. ATask guides
    2. BLanguage (chat)
    3. CClassification
    4. DImage
    5. EVideo
    6. FAudio
    7. GDocument processing
  4. 07Batch jobs
  5. 08Prompt caching
  6. 09Code with HIPS
  7. 10Coding-tool setup
    1. AHIPS Code
    2. BClaude Code
    3. CCodex
    4. DOpenCode
    5. EKilo
    6. FPi
    7. GQwen Code
    8. HCrush
    9. ICline
    10. JPrime Agent
    11. KAider
    12. LGoose
    13. MHermes Agent
    14. NGrok Build
    15. ODeepSeek Harness
    16. POther coding tools and editor integrations
  8. 11Command line
    1. AInstall and update
    2. BSign in
    3. CStatus and models
    4. DCoding agents
  9. 12Console
    1. AAccount
    2. BWorkspaces
    3. CAPI keys
    4. DSettings
    5. EUsage
    6. FModels
    7. GPlayground
    8. HDeployments
  10. 13Billing
  11. 14Provider setup
    1. AWhen it works
    2. BCommands
    3. CSettings
    4. DProvider Console
    5. EEarnings
    6. FCrash reports
    7. GData centers
  12. 15Semantic routing
  13. 16Guardrails
  14. 17Knowledge

Reference

  1. 18API reference
    1. AAuthentication
    2. BChat completions
    3. CResponses
    4. DMessages
    5. ECount tokens
    6. FModels
    7. GPrices API
    8. HTasks
    9. IEmbeddings and rerank
    10. JImages
    11. KJobs
    12. LUploads
    13. MFiles
    14. NBatches
    15. OWebhooks
    16. PVector stores
    17. QDeployments
    18. RRequirements and headers
    19. SErrors
    20. TUsage
    21. UVersioning
  2. 19Operating guidance
    1. ALimits
    2. BErrors
    3. CRetries and billing outcomes
    4. DIdempotency
    5. EStreaming
    6. FData handling
    7. GCompatibility matrix
  3. 20Changelog
Sheet indexAPI reference

Get started

  1. 01Developer hub
  2. 02Quickstart
  3. 03Migrate to HIPS

Guides

  1. 04HIPS SDK
  2. 05Import and run your model
  3. 06Model and task guides
    1. ATask guides
    2. BLanguage (chat)
    3. CClassification
    4. DImage
    5. EVideo
    6. FAudio
    7. GDocument processing
  4. 07Batch jobs
  5. 08Prompt caching
  6. 09Code with HIPS
  7. 10Coding-tool setup
    1. AHIPS Code
    2. BClaude Code
    3. CCodex
    4. DOpenCode
    5. EKilo
    6. FPi
    7. GQwen Code
    8. HCrush
    9. ICline
    10. JPrime Agent
    11. KAider
    12. LGoose
    13. MHermes Agent
    14. NGrok Build
    15. ODeepSeek Harness
    16. POther coding tools and editor integrations
  8. 11Command line
    1. AInstall and update
    2. BSign in
    3. CStatus and models
    4. DCoding agents
  9. 12Console
    1. AAccount
    2. BWorkspaces
    3. CAPI keys
    4. DSettings
    5. EUsage
    6. FModels
    7. GPlayground
    8. HDeployments
  10. 13Billing
  11. 14Provider setup
    1. AWhen it works
    2. BCommands
    3. CSettings
    4. DProvider Console
    5. EEarnings
    6. FCrash reports
    7. GData centers
  12. 15Semantic routing
  13. 16Guardrails
  14. 17Knowledge

Reference

  1. 18API reference
    1. AAuthentication
    2. BChat completions
    3. CResponses
    4. DMessages
    5. ECount tokens
    6. FModels
    7. GPrices API
    8. HTasks
    9. IEmbeddings and rerank
    10. JImages
    11. KJobs
    12. LUploads
    13. MFiles
    14. NBatches
    15. OWebhooks
    16. PVector stores
    17. QDeployments
    18. RRequirements and headers
    19. SErrors
    20. TUsage
    21. UVersioning
  2. 19Operating guidance
    1. ALimits
    2. BErrors
    3. CRetries and billing outcomes
    4. DIdempotency
    5. EStreaming
    6. FData handling
    7. GCompatibility matrix
  3. 20Changelog
18
  1. Docs/
  2. API reference/
  3. Errors
(Detail S)
llms.txt

Errors

On this sheet4 sections
  1. A refusal by plan
  2. On the Messages route
  3. Types
  4. Codes

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.

F
Fig. 1, sheet 18API reference

Envelope

00000000000000000000000000000000000000001{2  "error": {3    "message": "<a sentence a developer can act on>",4    "type": "<type>",5    "param": "<field or header, or null>",6    "code": "<code>"7  }8}
Envelope sample

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).

A refusal by plan

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

00000000000000000000000000000000000000001{"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"}}
A refusal by plan sample

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.

On the Messages route

Messages error

00000000000000000000000000000000000000001{"type": "error", "error": {"type": "invalid_request_error", "message": "<message>", "code": "<code>"}, "request_id": "req_..."}
Messages error sample

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.

Types

The type list is closed; a specific situation is a code under one of these types.

StatusTypeMeaning
400invalid_request_errorThe request cannot be served as sent; nothing is billed
401authentication_errorNo key, or a key the gateway does not accept
402insufficient_creditThe balance does not cover the request's maximum cost at the bound quote
403permission_error, workspace_suspendedThe key, plan or workspace may not do this
404not_found_errorA model, job, upload or route that does not exist for this key
429rate_limit_errorA limit of the key or workspace; Retry-After is sent
503overloaded_errorNo capacity under the request's requirements; Retry-After is sent
500api_errorA 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-After is sent
  • Status
    503
    Type
    overloaded_error
    Meaning
    No capacity under the request's requirements; Retry-After is sent
  • Status
    500
    Type
    api_error
    Meaning
    A fault in HIPS; nothing is billed

Codes

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.

StatusTypeCodeSituationRetry
400invalid_request_errorinvalid_jsonThe body is not JSON, or not an objectNo
400invalid_request_errormissing_required_parameterA required field or header is absent; param names itNo
400invalid_request_errorinvalid_typeA field has the wrong JSON typeNo
400invalid_request_errorinvalid_valueA 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 valuesNo
400invalid_request_errorunknown_parameterA field the gateway does not know, at any depth; param names itNo
400invalid_request_errorunsupported_parameterA 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 modelNo
400invalid_request_errorunsupported_valuen other than 1, stream_options without stream, a message role, part, item or tool type not accepted, a hosted tool that is not servedNo
400invalid_request_errorstateful_not_supportedState HIPS does not keep: store and metadata on chat completions; store: true, previous_response_id, conversation, metadata, background: true and item_reference on ResponsesNo
400invalid_request_errortype_not_servedPOST /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 typeOnce the type is served
400invalid_request_errorcontext_length_exceededThe 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 cutNo
400invalid_request_errormax_tokens_exceededmax_tokens (on Responses max_output_tokens) over the model's max_output_tokensNo
400invalid_request_errorinvalid_imageAn image part or input cannot be decoded, is of an unsupported type or over the pixel limitNo
400invalid_request_errorrequest_too_large, input_too_large, too_many_inputs, upload_too_largeA limit of the Limits pageNo
400invalid_request_errorinput_too_longOn POST /v1/rerank, a query or a document over 32 KiB of text, refused whole and never cutNo
400invalid_request_errorexceeds_time_limitAn 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, unchargedNo; send fewer or shorter inputs
400invalid_request_errortask_mismatchtask is not the model's task, or the model is not an embedding model or a reranker on its routeNo
400invalid_request_erroruse_jobsA task type that runs only as an asynchronous job (video_generation); the job routes are not built yetNo
400invalid_request_errornot_a_language_modelA task model named on an OpenAI-compatible routeNo
400invalid_request_errordeployment_stoppedThe dep_ is in stopped; start it in the ConsoleNo
400invalid_request_errorupload_not_found, upload_expired, upload_incomplete, upload_mismatch, upload_consumed, upload_purpose_mismatch, upload_region_mismatchAn 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 yetNo (upload_incomplete: after the PUT)
400invalid_request_errorinvalid_requirementA requirement header or field with an unknown valueNo
400invalid_request_errorrequirement_conflictTwo 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 meetNo
400invalid_request_errorstable_price_not_in_forcepricing_mode: stable with no stable price covering this workspace, model and periodNo
400invalid_request_errorinvalid_idempotency_key, idempotency_key_reused, idempotency_in_progressThe idempotency rulesThe last one, later
400invalid_request_errorrequest_timeoutThe body stopped arrivingYes
400invalid_request_errorrouter_no_candidateA 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, unchargedNo
400invalid_request_errorguardrail_blockedA 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, unchargedNo
400invalid_request_errorguardrail_input_too_longA content moderation guardrail with block cannot check all of the request's text; param is messagesNo
400invalid_request_errorcontent_refusedAn 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 chargedNo
400invalid_request_errorimage_withheldNot 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 chargedNo
400invalid_request_errortool_not_availableA hosted tool whose price per call is not published, so it is not offered yet. Knowledge is not switched on in production yetNo
400invalid_request_errorknowledge_not_availableA Knowledge route while Knowledge's prices are not in effect. Knowledge is not switched on in production yetNo
400invalid_request_errorlimit_reachedA file or knowledge base past a limit the message names. Knowledge is not switched on in production yetNo
400invalid_request_errorregion_unavailableA knowledge base in a region whose store does not exist yet. Knowledge is not switched on in production yetNo
400invalid_request_errorfile_too_large, invalid_file_format, batch_not_offeredA 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 yetNo
400invalid_request_errorstorage_marked_for_deletionOn 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 yetOnce credit brings the balance back to zero or above, which clears the mark at once (the Console answers the same code as a 409)
401authentication_errormissing_api_keyNo Authorization header, or not a bearer (on Messages, no x-api-key either)No
401authentication_errorinvalid_api_keyUnknown, malformed or revoked key or person's token; on Messages, x-api-key and Authorization carrying different values. The message never says whichNo
401authentication_errortoken_expiredA person's access token past its life; the tool refreshes it and sends the request againAfter the refresh
402insufficient_creditinsufficient_creditThe balance does not cover the request's maximum cost at the bound quoteAfter a top-up
402insufficient_creditbudget_exceededA 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 challengeAfter resets_at, or once the limit is raised
403permission_errorkey_scope_deniedThe 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 documentsNo
403permission_errorinsufficient_scopeA person's access token without the inference scopeNo; sign the tool in with the scope
403permission_errorregion_not_on_planA region requirement on a plan without region selectionNo
403permission_errormodel_not_on_planA 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 deploymentsAfter an owner or admin chooses a plan that includes it
403permission_errorpool_not_allowedA 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 acceptedNo
403permission_errormodel_not_allowed, region_not_allowedA model, or a region requirement, that an access guardrail keeps out, the guardrail named in the error's guardrail memberNo
403permission_errorguardrail_unsupportedA content moderation guardrail applies to text it does not scan yet: a batch, or a task request with text; the guardrail named, unchargedNo
403permission_errorworkspace_unverifiedThe 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 onAfter verification
403permission_errormember_unverifiedA 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 onAfter verification
403permission_erroraccount_restrictedThe workspace's owner, or the person a token belongs to, cannot use HIPS. The message says to contact HIPS supportNo; contact support
403workspace_suspendedworkspace_pausedThe 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 itAfter resolution
403workspace_suspendedplan_lapsedA 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 minuteAfter about a minute
403workspace_suspendedworkspace_deletedThe workspace is deleted (restorable 30 days)After restore
404not_found_errormodel_not_foundUnknown catalog id, alias, pinned id or dep_; another workspace's dep_; a name starting with hips-router that is not one of the four routersNo
404not_found_errorupload_not_found, file_not_found, batch_not_foundAn 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 yetNo
404not_found_errorknowledge_base_not_foundA knowledge base that is not the workspace's, or that is being deleted. Knowledge is not switched on in production yetNo
404not_found_errorresult_expiredA 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 onceNo
404not_found_errorroute_not_foundUnknown path, among them every /v1/jobs path (not built) and Knowledge's paths while Knowledge is switched offNo
404not_found_errorroute_not_availableA route that is built and not offered on this gateway: uploads, files and batches in production, and POST /v1/messages/count_tokensNo
404not_found_errormethod_not_allowedA known path with another method; Allow is sentNo
429rate_limit_errorrate_limit_exceededA rate limit; param is requests, tokens, uploads, batches (batches created per hour) or knowledge_search; Retry-AfterYes, after Retry-After
429rate_limit_errorconcurrency_limit_exceededToo many open batches; param is batches; Retry-AfterYes, after Retry-After
503overloaded_errorno_capacityNo 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 answerYes, after the given delay
503overloaded_errormodel_loadingEvery 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 chargedYes, after the given delay
503overloaded_errorcontext_size_not_measuredThe 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_capacityYes, or send a shorter prompt
503overloaded_errorpool_unavailableThe named pool has no eligible supply for this model now and fallback is off; the other pool may have; Retry-AfterYes, or with fallback
503overloaded_errordeployment_not_readyThe dep_ is allocating or loading, or waits for its version's tariff (tariff_pending); Retry-AfterYes
503overloaded_erroroverloadedEligible workers exist and every one is saturated, or the queue is full; Retry-AfterYes
503overloaded_errorguardrail_unavailableA 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; unchargedYes, unless the request requires a region
503overloaded_errorcontent_check_unavailableThe 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; unchargedYes, after Retry-After
500api_errorinternal_errorA fault in HIPS. Nothing billedOnce
500api_errorattempt_failedEvery attempt failed for a reason that is not the client's and retries are exhausted. Nothing billedOnce
500api_errordeadline_exceededThe request's own time bound ended it; x-should-retry: false. Nothing billedNot 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; param names 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: 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
    unsupported_value
    Situation
    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
    Retry
    No
  • Status
    400
    Type
    invalid_request_error
    Code
    stateful_not_supported
    Situation
    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
    Retry
    No
  • Status
    400
    Type
    invalid_request_error
    Code
    type_not_served
    Situation
    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
    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'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
    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
    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
    task is 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 in stopped; 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_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
    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 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
    Retry
    No
  • Status
    400
    Type
    invalid_request_error
    Code
    stable_price_not_in_force
    Situation
    pricing_mode: stable with 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 (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
    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
    400
    Type
    invalid_request_error
    Code
    guardrail_input_too_long
    Situation
    A content moderation guardrail with block cannot check all of the request's text; param is messages
    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 (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
    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 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
    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 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
    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}/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
    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 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
    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 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
    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 full writing a knowledge base's documents
    Retry
    No
  • Status
    403
    Type
    permission_error
    Code
    insufficient_scope
    Situation
    A person's access token without the inference scope
    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-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
    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 guardrail member
    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's dep_; a name starting with hips-router that 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-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
    Retry
    No
  • Status
    404
    Type
    not_found_error
    Code
    route_not_found
    Situation
    Unknown path, among them every /v1/jobs path (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; Allow is sent
    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
    429
    Type
    rate_limit_error
    Code
    concurrency_limit_exceeded
    Situation
    Too many open batches; param is batches; 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, 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
    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_ is allocating or loading, 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 block could 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

  • Operating guidance: errors
  • Retries and billing outcomes
Previous sheetRequirements and headers
Next sheetUsage
Sheet
18 of 20
Detail
S
Updated
2026-11-16
Sign in to the Console

On this sheet

  1. A refusal by plan
  2. On the Messages route
  3. Types
  4. Codes

Product

  • Inference
  • Models
  • Deploy your model
  • Always-on GPU capacity
  • How it works
  • Use cases
  • Pricing

Developer

  • Docs
  • Quickstart
  • Migrate to HIPS
  • HIPS SDK
  • Batch jobs
  • API reference

Provider

  • Earn with your GPU
  • Register GPU interest
  • Download for Mac
  • Download for Windows
  • Download for Linux

Resource

  • Security and Data
  • Resources
  • llms.txt

Compare

  • OpenRouter alternatives
  • Together AI alternatives
  • Groq alternatives
  • All comparisons

Company

  • About
  • Contact
  • Affiliate program
  • HIPS Payments

Legal

  • Legal
  • Consumer Health Data Privacy Policy
  • Report content
  • Cookie preferences

Support

  • Contact HIPS
  • Looking for payments support?

HIPS. AI inference for builders.

hips.com

Hyperscale Inference Processing Systems OÜ