Error code reference

Classify AIXHUB, compatibility-layer, upstream, and client errors before deciding whether a request is safe to retry.

Use this reference after preserving the original HTTP status, response body, request ID, Retry-After value, and final streaming event. Similar failures can use different envelopes across OpenAI Responses and Anthropic Messages, so diagnose the observable status and source instead of matching only one message string.

Prerequisites

Start with an HTTP status, error code, or terminal stream event. If all you know is that the request failed, use Troubleshooting first to reproduce one minimal request.

Steps

Error code table

AIXHUB common errors and actions
Scenario	HTTP / state	Possible codes	Source	Meaning	Action	When to retry
API key missing or invalid	401	`API_KEY_REQUIREDINVALID_API_KEY`	AIXHUB	The service did not receive a valid API key, or the key was revoked, disabled, or copied incorrectly.	Use an API key rather than a console password. Copy the full key again and check which variable the client reads.	Retry after correcting the key or authentication settings.
Account, group, or subscription cannot access the model	403	`ACCESS_DENIEDAPI_KEY_EXPIREDGROUP_NOT_ALLOWED`	AIXHUB	The key may be valid, but the account, key group, expiry, or subscription does not permit this request.	Check the account, API key, plan, or subscription state and confirm that the model belongs to the key's group.	Retry after the access or plan state updates. Do not flood retries before access is corrected.
Account balance is insufficient	403	`INSUFFICIENT_BALANCE`	AIXHUB	The available balance is too low to accept the request. This is normally not a 429 rate limit.	Check Dashboard and Usage records, complete the billing action, and confirm the balance updated.	Retry after the balance updates. Check usage before replaying generation requests.
Request format or model parameter is invalid	400	`invalid_request_error`	Compatibility layer	The endpoint, JSON shape, required field, model ID, or parameter does not match the selected protocol.	Return to the relevant API or client guide and check the Base URL, request format, and model ID from Available channels.	Retry after correcting the request.
Request content is too large	413 or 400	`invalid_request_error`	Compatibility layer	The prompt, attachment, image, or complete request exceeds the current endpoint limit.	Shorten the input, remove unnecessary attachments, or split the task into smaller requests.	Retry after reducing the content.
Rate, concurrency, or quota limit	429	`rate_limit_errorrate_limit_exceededUSAGE_LIMIT_EXCEEDED`	AIXHUB or upstream	Request rate, concurrent jobs, or key quota temporarily exceeds a limit.	Reduce concurrency and request frequency. Honor Retry-After when it is present.	Retry a limited number of times after waiting. Do not rotate keys to evade a limit.
Model is currently unavailable	400, 403, or 503	`invalid_request_errorapi_error`	AIXHUB or upstream	The model ID is wrong, the model is outside the current group, or no account can currently handle it.	Recheck Available channels, the model ID, protocol, key group, and service status.	Retry after the model recovers or choose one currently shown as available.
Upstream or routing failure	502 or 503	`upstream_errorserver_erroroverloaded_error`	Upstream or routing	AIXHUB accepted the request, but an upstream account, route, or service capacity could not complete it.	Keep the request ID and time, check Usage records, then inspect service status or contact support.	Retry a limited number of times after waiting; do not loop indefinitely.
Responses stream failed after starting	HTTP 200, then stream event	`response.failed`	Compatibility layer	The connection starts with 200 but the SSE stream ends with response.failed. Checking only the initial status is not enough.	Read the stream through a completion or failure event, treat partial output as incomplete, and keep the event error.	Check usage and acceptance state before starting a new stream.
Client or network disconnected	Client or network state	`N/A`	Client or network	Client cancellation, proxy timeout, network loss, or process exit can close a request before completion.	Check client logs, proxy, and timeout settings, then use Usage records to see whether the request was accepted.	Confirm there was no duplicate charge or execution before creating a new request.

The source column distinguishes AIXHUB-observable states from compatibility-layer, upstream, and client/network failures. Provider-specific or internal codes can vary by deployment and are not a permanent AIXHUB contract unless explicitly documented as such.

How to use this reference

Preserve the HTTP status, request ID, Retry-After, and the complete redacted response.
Read code, error.type, error.code, and message from the actual envelope, then compare the possible codes in the table.
Use the Source column to separate AIXHUB, compatibility-layer, upstream, and client/network failures.
Correct the cause described in the Action column. Send the request again only when it satisfies the retry boundaries below.
If the source is still unclear, return to Troubleshooting to run the minimal request and compare Usage records.

Verification

After applying the table's action, repeat the minimal request once. Confirm the final HTTP status or stream terminal event is successful and that Usage matches the test time and model.

The corrected minimal request completes once, its final status is successful, and the Usage record matches the local test.

Troubleshooting

Searchable code index

Authentication and access: API_KEY_REQUIRED, INVALID_API_KEY, ACCESS_DENIED, API_KEY_EXPIRED, GROUP_NOT_ALLOWED.
Billing: INSUFFICIENT_BALANCE is HTTP 403, not a 429 rate limit.
Request shape and model: invalid_request_error, api_error.
Limits: rate_limit_error, rate_limit_exceeded, USAGE_LIMIT_EXCEEDED.
Temporary service failures: upstream_error, server_error, overloaded_error.
Responses stream failure: response.failed can arrive after the connection started with HTTP 200.

Retry boundaries

Correct 400, 401, 403, and 413 before retrying. Do not replay the same invalid or unauthorized request.
For 429, honor Retry-After, lower concurrency, and use capped exponential backoff with jitter.
Retry 502 or 503 only a limited number of times. Stop and preserve the request ID when failures continue.
Automatically retry only idempotent operations or generation requests confirmed as unaccepted.
Never concatenate partial stream output with the output from a later retry.

For support, include the failure time and time zone, request ID, client name and version, endpoint, protocol, model, HTTP or event status, a redacted response, and whether Usage contains the request. Never include a complete API key, cookie, console token, prompt, or unredacted user data.

Next step

Return to Troubleshooting, inspect Usage, or rerun the minimal request from Authentication and Base URL. Protocol-specific guidance is available in OpenAI Responses and Anthropic Messages.

Official sources

Last verified: 2026-07-14