Error Codes and Troubleshooting

This page helps API customers diagnose common request failures when using VLX FLUX through OpenAI-compatible SDKs, HTTP requests, CLI tools, or third-party clients.

Quick Checklist

Before checking detailed error codes, confirm:

• The API key is correct, active, and copied without extra spaces.
• The Base URL is https://api.vlxflux.io/v1.
• The request path is correct, such as /chat/completions or /models.
• The selected model is available to your account.
• Your account has sufficient balance.
• Your local network, proxy, or DNS settings are working.

Common HTTP Errors

Error	Meaning	What to do
400 Bad Request	Request body or parameter format is invalid	Check JSON syntax, required fields, and parameter types
401 Unauthorized	API key is missing, invalid, disabled, or incorrectly formatted	Check the Authorization: Bearer YOUR_API_KEY header
403 Forbidden	The key does not have permission for the model or group	Check model access, group permissions, and account status
404 Not Found	The URL or path is incorrect	Confirm the Base URL and avoid duplicated /v1
408 Request Timeout	The request took too long	Retry later or reduce request complexity
429 Too Many Requests	Rate limit, concurrency limit, or quota limit was reached	Lower request frequency or concurrency
500 Internal Server Error	Platform or upstream error	Retry later and contact support if it persists
502 Bad Gateway	Upstream model provider returned an invalid response	Retry later or switch models
503 Service Unavailable	Service or upstream model is temporarily unavailable	Retry later or switch to another available model
504 Gateway Timeout	Upstream model response timed out	Retry, reduce context size, or switch models

Authentication Problems

401 Unauthorized

Usually caused by one of the following:

• API key is missing
• API key was copied incorrectly
• API key has extra spaces or line breaks
• API key has been disabled or deleted
• The request does not include the Bearer prefix

Correct header:

Authorization: Bearer YOUR_API_KEY

URL Problems

404 Not Found

Check whether the client expects a Base URL or a full endpoint.

Correct Base URL:

https://api.vlxflux.io/v1

Correct chat endpoint:

https://api.vlxflux.io/v1/chat/completions

Common mistakes:

• https://api.vlxflux.io
• https://api.vlxflux.io/v1/v1
• https://vlxflux.com
• Dashboard URLs instead of API URLs

Model Problems

model not found

This means the model name is incorrect or unavailable to your account.

First query the model list:

curl https://api.vlxflux.io/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Then use an exact model ID returned by the API or shown in the dashboard.

403 Forbidden

The model may exist, but your API key may not have permission to use it. Check your account permissions, balance, and model group availability.

Billing Problems

Insufficient balance

If the account balance is too low, API calls may fail. Recharge your account or choose a lower-cost model.

You can check balance and usage history in the dashboard.

Unexpected spending

Spending may be affected by:

• Input token length
• Output token length
• Model base price
• Model group multiplier
• Streaming and repeated retries
• Multiple clients sharing the same API key

Review usage history in the dashboard if spending is higher than expected.

Rate Limit Problems

429 Too Many Requests

Reduce request frequency or concurrency. If you are using an automated task, add retry logic with backoff.

For example:

• Wait before retrying
• Limit concurrent requests
• Reduce long-context requests
• Avoid retry loops that immediately resend failed requests

Upstream Problems

Some models depend on upstream providers. If an upstream model is temporarily unavailable, you may see 500, 502, 503, or 504 errors.

Recommended actions:

• Retry later
• Switch to another available model
• Reduce context size or output length
• Contact support with the request time, model name, and error message

What to Provide When Contacting Support

To help support diagnose faster, provide:

• Request time
• API endpoint
• Model name
• Error code and error message
• Whether the request was made through code, CLI, or a third-party client
• A sanitized request example without your API key

Never send your full API key in screenshots or support messages.