Troubleshooting

Diagnose AIXHUB API failures by source, HTTP status, response fields, and streaming events.

AIXHUB supports Anthropic, OpenAI, and Gemini-compatible protocols, so similar failures do not always use the same JSON envelope. Preserve the original HTTP status, error code, request ID, and streaming event before deciding whether the failure came from AIXHUB, the compatibility layer, an upstream provider, or the client network.

Status or event	Usually means	First action
400	Invalid request format, parameter, or key transport	Correct the request instead of replaying it unchanged
401	Missing, invalid, or disabled AIXHUB key	Check the authentication header and key state
403	Permission, subscription, group, key expiration, or balance issue	Inspect the account and key in the panel
413	Request body or estimated token count is too large	Reduce the input before testing again
429	Key quota, rate, concurrency, or queue limit	Honor `Retry-After` and lower load
502	Upstream authentication, connection, or failover failure	Save the request ID and retry only a limited number of times
503	No account is available or an upstream is overloaded	Wait for capacity or inspect channel health
Streaming failure after HTTP 200	The connection opened, but SSE ended with an error event	Parse the terminal event instead of checking only the initial status

Prerequisites

Prepare a known working test key with the minimum required permissions. Do not substitute a console login token for an API key.
You can sign in to AIXHUB and open API keys, Dashboard, Available channels, and Usage records.
Record the failure time and time zone, complete endpoint, protocol, model ID, client name, and client version.
Confirm screenshots, terminal output, logs, and support messages exclude complete keys, cookies, prompt content, and user data.

Steps

Capture the complete response

Reproduce the problem with a minimal request. This command includes HTTP status and response headers without placing the key directly in the command text.

curl -i https://api.aixhub.org/v1/messages \
  -H "x-api-key: $AIXHUB_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  --data '{"model":"panel-model-id","max_tokens":16,"messages":[{"role":"user","content":"Reply OK"}]}'

In Windows PowerShell, use curl.exe so the curl alias is not resolved as another command.

curl.exe -i https://api.aixhub.org/v1/messages `
  -H "x-api-key: $env:AIXHUB_API_KEY" `
  -H "anthropic-version: 2023-06-01" `
  -H "content-type: application/json" `
  --data '{"model":"panel-model-id","max_tokens":16,"messages":[{"role":"user","content":"Reply OK"}]}'

For SSE, add -N and continue reading until a completion or error event. Before sharing diagnostics, redact Authorization, x-api-key, cookies, complete prompts, and signed query parameters in image URLs.

Read error fields in order

Start with the HTTP status and Retry-After. When Retry-After is present, it takes priority over a client-selected delay.
Record the request ID from response headers or the response body. Field names can differ by protocol.
In JSON, look for the top-level code, then error.type, error.code, and message.
In SSE, record both event: and data:. OpenAI Responses clients must process terminal events such as response.completed and response.failed.
Compare the table's Source column. Stable AIXHUB codes, compatibility codes, and provider codes are not one universal contract.

Look up an error code

If you already have an HTTP status, error code, or terminal stream event, go directly to the error code reference for its source, meaning, action, and retry boundary. The complete table is maintained only on that page so the guidance cannot drift between two copies.

Verification

Repeat the minimal request with the same key and model, then confirm the expected successful HTTP status.
For streaming, require the correct completion event. Do not treat the request as successful only because it started with HTTP 200.
Match time, model, protocol, status, and cost in Usage records. Confirm manual retries did not create duplicate records.
Restore long input, images, tool calls, streaming, and concurrency one item at a time.

The minimal request succeeds consistently, the stream has a complete terminal event, and AIXHUB Usage records match the local test time, model, and status.

Troubleshooting

Build a support bundle

Include:

Failure time and time zone
request ID
Client name and version
Complete endpoint, protocol, and model ID
HTTP status or terminal SSE event
Response body with sensitive values redacted
Whether Usage records contain the request
Minimal reproduction steps and fixes already attempted

Never include a complete API key, cookie, console token, complete prompt, or unredacted user data.

Next step

If you have a status or code, continue with the error code reference. If the failure cannot be reproduced, return to Authentication and Base URL, then compare the request in Usage records and check Available channels.