Errors and troubleshooting

What an error looks like

On an error, NoviaHub returns an HTTP status code (such as 401, 403 or 503) and a JSON body. Most errors use the OpenAI format:

{
  "error": {
    "message": "Invalid token (request id: 202609281537468941710008268d9d6GzbHDLkB)",
    "type": "new_api_error",
    "param": "",
    "code": ""
  }
}

• message: what went wrong. The request id in brackets at the end identifies this request; include it when you contact support.
• code: the error code. Some errors have none, and then it is an empty string.
• type: for errors NoviaHub produces itself, usually new_api_error, or invalid_request_error when the address doesn’t exist. Errors returned by the upstream model vendor keep the vendor’s original value.

When you call the Anthropic endpoint (/v1/messages), some errors come back in Anthropic’s format, with an extra "type": "error" on the outside:

{
  "type": "error",
  "error": {
    "type": "new_api_error",
    "message": "用户额度不足, 剩余额度: ＄0.000000 (request id: ...)"
  }
}

The Anthropic format has only type and message and no code field, so tell errors apart by message.

Errors that stop a request as soon as it arrives, such as an invalid key or a model outside the key’s allowed list, still come back in the OpenAI format above, even on /v1/messages.

Also note:

• Language of error messages: some messages are translated into English or Chinese, for example Invalid token and 无效的令牌. The interface language saved in your account comes first (switching the language while signed in to the NoviaHub website saves it to your account), then the Accept-Language request header, and English when neither is set. Where a message has a Chinese translation, the tables below show it too; messages that exist only in Chinese are marked, with an English gloss.
• Request ID: every response carries an X-Oneapi-Request-Id header whose value is the request ID.

Common errors

The entries below were triggered on a local test instance running the same version as production and checked against the gateway source.

401: authentication failed

Message	Cause	What to do
Invalid token (Chinese: 无效的令牌)	No API key was sent, the key is wrong, or the key is disabled, expired or exhausted. All of these give exactly the same error.	Check the key’s status on the API Keys page. Make sure the key was copied in full, without extra spaces or line breaks.
Same as above	The key is in the wrong header, for example x-api-key or x-goog-api-key on /v1/chat/completions.	Use Authorization: Bearer <API key>, or the header listed in Base URLs and protocols.

403: not allowed

Message	Code	Cause	What to do
This token has no access to model {model} (Chinese: 该令牌无权访问模型 {model})	(empty)	The key has Model Limits set and this model isn’t in the allowed list	Edit the key and add the model to Model Limits, or clear the limits
您的 IP 不在令牌允许访问的列表中 (Chinese only: “your IP is not in the key’s allowed list”)	access_denied	The key has an IP whitelist and your current IP isn’t in it	Edit the key’s IP whitelist (one IP per line), or clear it
用户额度不足, 剩余额度: ＄0.000000 (Chinese only: “insufficient user quota, remaining: $0.000000”)	insufficient_user_quota	Your account balance is used up (0 or negative)	Top up in Wallet
预扣费额度失败, 用户剩余额度: ..., 需要预扣费额度: ... (Chinese only: “pre-charge failed, remaining: …, required: …”)	insufficient_user_quota	You still have some balance, but less than this request’s pre-charge estimate; see Billing	Top up, or send less input in this request
token quota is not enough, token remain quota: ..., need quota: ...	pre_consume_token_quota_failed	The key has a quota cap, and what’s left isn’t enough for this request’s pre-charge	Edit the key: raise its quota or turn on Unlimited Quota
普通用户不支持指定渠道 (Chinese only: “regular users can’t choose a channel”)	(empty)	Something like -<number> was appended to the end of the key	Use the key exactly as copied from the API Keys page

400: something is wrong with the request

Message	Code	Cause	What to do
Model name not specified, model name cannot be empty (Chinese: 未指定模型名称，模型名称不能为空)	(empty)	The request has no model field	Add the model name
field messages is required	invalid_request	A required field is missing	Add the fields listed in the API reference
Invalid request: ... invalid JSON request body (in Chinese it starts with 无效的请求，)	(empty)	The request body isn’t valid JSON	Check that quotes, commas and brackets match
模型 {model} 的价格尚未由管理员配置... (in both Chinese and English)	model_price_error	This model isn’t open for use	Pick a model that is listed on Models & Pricing
unsupported model modifier "..." / invalid effort modifier value "..."	convert_request_failed	The @ modifier after the model name is wrong	Fix it as described in Reasoning and thinking
n must be an integer between 1 and 128	invalid_request	The number of images to generate is out of range	Set n between 1 and 128

404: wrong address

Message	Cause	What to do
Invalid URL (POST /v1/...)	The path doesn’t exist. Usually /v1 was added or left out, or you called an endpoint NoviaHub doesn’t provide (such as /v1/messages/count_tokens or Gemini’s :countTokens)	Check the address against Base URLs and protocols

503: model temporarily unavailable

Message	Code	Cause	What to do
No available channel for model {model} under group default (distributor) (Chinese: 分组 default 下模型 {model} 无可用渠道（distributor）)	model_not_found	The model name is wrong (case, hyphens, extra spaces), or the model has no working route right now	Copy the exact model ID from Models & Pricing. If the name is right and the error persists, try again later or contact support

Other cases

What you see	Cause	What to do
HTTP 500, get file data failed: ... or get file data from '...' failed: ..., code convert_request_failed	An image link in the messages couldn’t be downloaded	Send the image as base64, or use a link reachable from the public internet; see Image input
HTTP 500, not supported model for image generation, only imagen models are supported	A Gemini image model was called through /v1/images/generations	Use the Gemini or Chat endpoint; see Image generation
HTTP 429 or 5xx with a message from the model vendor	The upstream vendor is rate-limiting or failing. NoviaHub passes on the vendor’s status code and message unchanged, and forwards its Retry-After header when there is one.	Retry later; see the retry advice below
HTTP 200, but the body is a whole web page (HTML) and your program can’t parse JSON	/v1 is missing from the OpenAI address, so the request landed on the website	Change the base URL to https://noviahub.com/v1
An HTML error page (not JSON), with a status such as 403, 502 or 524	The request was stopped by the network protection or proxy in front of the site before it reached NoviaHub, or it timed out	Note the time, the address and the status code, and contact support

When to retry

• Retry: 429 (rate limited) and 5xx (server or upstream errors). Wait before retrying, double the wait after each failure (for example 1 s, 2 s, 4 s…) and cap the number of retries. If the response has Retry-After, wait at least that many seconds.
• Don’t retry: 400, 401, 403 and 404. These are problems with the request itself or your account settings; sending the same request again gives the same error. Fix it using the tables above first.

Failed requests aren’t charged: the pre-charge is returned. See Billing.

Contact support

Email support@noviahub.com with:

1. the request id from the error message, or the value of the X-Oneapi-Request-Id response header;
2. when it happened (to the minute, with your time zone);
3. the address and model you called, and the full error.

Never send your API key by email.