Fluxix error codes

Errors from /v1/chat/completions have a top-level code in the body with the Fluxix error code. Most errors also send it in the x-fluxix-error-code header. Errors follow the OpenAI error shape with extra fields such as cause, suggested_action and violations. For provider errors, Fluxix passes on the provider's HTTP status. Approval requests and self-corrections are not errors; they return HTTP 200.

CodeStatusMeaning and fix
AUTH_MISSING_CREDENTIALS401No API key was sent. Send your key as the SDK api_key (Authorization: Bearer fx_live_…) or in the x-api-key header.
AUTH_INVALID_API_KEY401The key does not match any key in Fluxix. Check for typos or extra whitespace, and confirm the environment variable holds the right key.
AUTH_EXPIRED_API_KEY401The key has passed its expiry date. Create a new key in the dashboard under API Keys.
AUTH_REVOKED_API_KEY401The key was revoked. Ask a project admin for an active key.
AUTH_INVALID_TOKEN401A dashboard session token failed verification. Sign in again. Agents should use an API key, not a session token.
AUTH_EXPIRED_TOKEN401A dashboard session token has expired. Sign in again to get a fresh session.
FORBIDDEN_INSUFFICIENT_ROLE403Your role cannot perform this action. Ask an organization admin for the editor or admin role.
PROJECT_ACCESS_DENIED403The key does not belong to the project you referenced. Use the API key created for that project.
PLAN_LIMIT_EXCEEDED403Your organization has reached its plan's quota. Upgrade the plan in the Billing tab, or contact us.
INVALID_JSON_BODY400The body is not valid JSON. Send Content-Type: application/json with a valid JSON body.
INVALID_REQUEST_PAYLOAD400A field is missing or has the wrong type, or the provider settings are invalid. Read the details array in the response for the exact field. Check x-provider-base-url if you set it.
MISSING_REQUIRED_PARAMETER400Fluxix could not tell which project the request is for. Use a project API key, or include projectId in the request body.
PROJECT_NOT_FOUND404No project matches the ID you sent. Check the project ID.
AGENT_NOT_FOUND404No agent matches the ID you sent. Check the agent ID.
AUDIT_LOG_NOT_FOUND404No audit log event matches the ID you sent. Check the event ID in the audit log.
CLIENT_CONNECTION_ABORTED499Your client closed the connection before the response finished. Raise your client timeout for long responses, or use streaming.
INPUT_POLICY_VIOLATION403The prompt matched one of your input rules. See violations[0].ruleName for the rule. Tell the user, or adjust the rule in the Policy Studio.
TOOL_EXECUTION_BLOCKED403The model tried to call a tool with arguments a block rule does not allow. See violations for the rule. To let the model retry with safer arguments instead, set the rule to self-correct.
OUTBOUND_PII_LEAK_BLOCKED403The model's response contained personal data that your outbound PII settings block. See violations for what was found, and review the outbound settings in PII Shield.
UPSTREAM_AUTHENTICATION_FAILED401No provider API key was sent, or the provider rejected it. Check the key in x-provider-key and that the provider account has credit.
UPSTREAM_RATE_LIMIT_EXCEEDED429You hit the provider's rate limit. Retry with exponential backoff, or raise your quota with the provider.
UPSTREAM_MODEL_NOT_FOUND404The provider returned 404, usually because it does not recognise the model or your account cannot use it. Check the model name against the provider's documentation.
UPSTREAM_CONTEXT_LENGTH_EXCEEDED400The provider returned 400 and its message mentions the context or token limit. Trim the conversation history or use a model with a larger context window.
UPSTREAM_INVALID_REQUEST400The provider returned 400 for another reason, such as an unsupported parameter. The cause field contains the provider's own message.
UPSTREAM_TIMEOUT504The provider returned 504, or the connection to it timed out. Retry, lower max_tokens, or use streaming for long responses.
UPSTREAM_CONNECTION_REFUSED502Fluxix could not connect to the provider. For local models, check the server is running and reachable at x-provider-base-url.
UPSTREAM_SERVICE_UNAVAILABLE503The provider returned 503: it is down or overloaded. Retry with backoff and check the provider's status page.
UPSTREAM_BAD_GATEWAYProvider's status, or 502The provider returned any other error status (for example 500 or 529), or the request to it failed for another reason. Read cause for the provider's message. For a custom endpoint, make sure it is OpenAI-compatible.
EMPTY_UPSTREAM_STREAM502A streaming request came back with no data. Check that the model supports streaming, then retry.
INTERNAL_SERVER_ERROR500An unexpected error inside the gateway. Retry once. If it continues, contact us with the requestId from the response.