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 indexOperating guidance

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
19
  1. Docs/
  2. Operating guidance/
  3. Errors
(Detail B)
llms.txt

Errors

On this sheet8 sections
  1. What to do, by status
  2. 400: the request cannot be served as sent
  3. 401, 402 and 403
  4. 404
  5. 429
  6. 503 and 500
  7. A stream that fails after it started
  8. The status line

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.

F
Fig. 1, sheet 19Operating guidance

What to do, by status

StatusTypeWhat to do
400invalid_request_errorFix the request. Never retry it unchanged. The message names the field, the model, the limit and the count.
401authentication_errorCheck HIPS_API_KEY and the Authorization: Bearer header. The message never says whether a key is unknown or revoked.
402insufficient_creditTop 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.
403permission_error, workspace_suspendedThe key's kind, the plan, the pool or the workspace's state refuses the request; the message names the Console screen that resolves it.
404not_found_errorThe id, the route or the result does not exist for this key. Never retry unchanged.
429rate_limit_errorWait Retry-After seconds, then retry. Nothing was charged.
503overloaded_errorWait Retry-After seconds, then retry; or, for pool_unavailable, enable fallback if your data-use and region rules allow it. Nothing was charged.
500api_errorRetry 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_KEY and the Authorization: Bearer header. 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_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.
  • 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-After seconds, then retry. Nothing was charged.
  • Status
    503
    Type
    overloaded_error
    What to do
    Wait Retry-After seconds, then retry; or, for pool_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-id to support.

400: the request cannot be served as sent

  • invalid_json: The body is not JSON, or not an object. Retry: No.
  • missing_required_parameter: A required field or header is absent; param names it. Retry: No.
  • invalid_type: A field has the wrong JSON type. Retry: No.
  • 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. Retry: No.
  • unknown_parameter: A field the gateway does not know, at any depth; param names 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; param names it and message names the model. Retry: No.
  • 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. Retry: No.
  • 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. Retry: No.
  • 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. Retry: Once the type is served.
  • 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. Retry: No.
  • max_tokens_exceeded: max_tokens (on Responses max_output_tokens) over the model's max_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: On POST /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: task is 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: The dep_ is in stopped; start it in the Console. Retry: No.
  • 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. 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 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.
  • stable_price_not_in_force: pricing_mode: stable with 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 (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.
  • 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. Retry: No.
  • guardrail_input_too_long: A content moderation guardrail with block cannot check all of the request's text; param is messages. 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 (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.
  • 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. 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, 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.
  • 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. 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).

401, 402 and 403

  • missing_api_key: No Authorization header, or not a bearer (on Messages, no x-api-key either). Retry: No.
  • 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. 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 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.
  • 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. Retry: No.
  • insufficient_scope: A person's access token without the inference scope. 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 (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.
  • 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's guardrail member. 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.

404

  • 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. Retry: No.
  • 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. 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 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.
  • route_not_found: Unknown path, among them every /v1/jobs path (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, and POST /v1/messages/count_tokens. Retry: No.
  • method_not_allowed: A known path with another method; Allow is sent. Retry: No.

429

  • rate_limit_exceeded: A rate limit; param is requests, tokens, uploads, batches (batches created per hour) or knowledge_search; Retry-After. Retry: Yes, after Retry-After.
  • concurrency_limit_exceeded: Too many open batches; param is batches; Retry-After. Retry: Yes, after Retry-After.

503 and 500

  • 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, 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.
  • 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: The dep_ is allocating or loading, 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 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.
  • 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, after Retry-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.

A stream that fails after it started

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.

The status line

GET/statusserved

The 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

  • Errors reference
  • Retries and billing outcomes
Previous sheetLimits
Next sheetRetries and billing outcomes
Sheet
19 of 20
Detail
B
Updated
2026-11-16
Sign in to the Console

On this sheet

  1. What to do, by status
  2. 400: the request cannot be served as sent
  3. 401, 402 and 403
  4. 404
  5. 429
  6. 503 and 500
  7. A stream that fails after it started
  8. The status line

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Ü