Inference errors

When Hyperbolic can’t accept an inference request, it returns an HTTP error status. Use the status code to decide whether to retry.

Authentication, plan, and balance errors (401, 402, 403) return a JSON body with code and message at the top level, as shown below. The status says which kind of problem it is; use the code to decide what to fix.
Other errors can come from the API gateway, the model server, or an upstream model provider, and their body format varies. Handle them by HTTP status code. For example, an unknown model ID returns 404 with {"message": "Model not found", "type": "Not Found", "code": 404}.

The OpenAI SDKs raise an exception with the status code for every error.

Authentication, plan, and balance errors

Requests that fail an authentication, plan, or balance check return one of three statuses, each with a code and a readable message:

401: the credential is missing, invalid, or expired.
402: the account or Organization has no credits left.
403: the account’s plan doesn’t include inference.

{
  "code": "api_key_invalid",
  "message": "..."
}

The message says what to do next and may change. The code doesn’t change, so branch on code in your client.

Status	`code`	Meaning	What to do
`401`	`api_key_missing`	No API key was sent	Send your key in the `Authorization` header as `Bearer YOUR_API_KEY`
`401`	`api_key_malformed`	The credential isn’t an API key the service accepts	Use an `sk_live_` key from Settings > API Keys
`401`	`api_key_invalid`	The key doesn’t exist or is wrong	Check the key, or create a new one
`401`	`api_key_revoked`	The key was revoked	Create a new key under Settings > API Keys
`401`	`legacy_key_unsupported`	The key uses the older format from the previous inference API	Create a new `sk_live_` key
`401`	`account_not_found`	No account matches the dashboard session	Sign in again. Contact support if it persists
`401`	`account_plan_unknown`	Hyperbolic couldn’t read your plan	Contact support
`401`	`session_expired`	The dashboard session expired	Sign in again
`401`	`session_invalid`	The dashboard session couldn’t be verified	Sign in again
`402`	`insufficient_balance`	The account or Organization has no credits left	Add credits under Billing
`403`	`inference_requires_pro`	The personal account is on the Free Tier	Upgrade with a one-time $5 deposit under Settings > Plan, or use an Organization API key

The session_* and account_not_found codes apply to requests from the Model Playground, which uses your dashboard session instead of an API key.

After you upgrade your plan, retry after about 30 seconds. After you add credits, retry after a minute or two.

Other status codes

Status	Meaning	What to do
`400`	The request isn’t valid. For `glm-5.3-flash`, this includes a prompt plus `max_tokens` that doesn’t fit in the context window	Check the request body, or shorten the prompt or lower `max_tokens`. Don’t retry it unchanged
`404`	The model ID doesn’t exist, or the URL is wrong. Requests to the previous API at `api.hyperbolic.xyz` return `404`	Use a model ID from Available models and the base URL `https://api.hyperbolic.ai/inference/v1`
`429`	The API key sent more than 300 requests in a minute	Retry with exponential backoff. For a higher limit, contact sales
`500`, `502`, `503`, `504`	Hyperbolic or the model is temporarily unavailable. A `503` can also mean the authentication check timed out	Retry with exponential backoff. Contact support if it persists

You aren’t charged for requests that return an error.

Retry with backoff

Retry 429 and 5xx responses, waiting longer after each attempt. Don’t retry 400, 401, 402, or 403 responses, because the same request fails again until you fix it: the request, the credential, the balance, or the plan.

import time
import requests

RETRYABLE = {429, 500, 502, 503, 504}

def chat(data, api_key, max_retries=4):
    url = "https://api.hyperbolic.ai/inference/v1/chat/completions"
    headers = {"Authorization": f"Bearer {api_key}"}
    for attempt in range(max_retries + 1):
        response = requests.post(url, headers=headers, json=data, timeout=120)
        if response.status_code not in RETRYABLE or attempt == max_retries:
            response.raise_for_status()
            return response.json()
        time.sleep(2 ** attempt)  # 1, 2, 4, 8 seconds

The OpenAI SDKs retry 429 and 5xx responses automatically. Set max_retries (Python) or maxRetries (Node.js) on the client to change how many times.

Overview

GPUs

Managed Kubernetes

Rental Operator

Inference

Account & Billing

API Reference

References

Authentication, plan, and balance errors

Other status codes

Retry with backoff

Next steps

Account management

Getting support

​Authentication, plan, and balance errors

​Other status codes

​Retry with backoff

​Next steps

Account management

Getting support

Authentication, plan, and balance errors

Other status codes

Retry with backoff

Next steps