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.
| Code | Status | Meaning and fix |
|---|---|---|
| AUTH_MISSING_CREDENTIALS | 401 | No 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_KEY | 401 | The 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_KEY | 401 | The key has passed its expiry date. Create a new key in the dashboard under API Keys. |
| AUTH_REVOKED_API_KEY | 401 | The key was revoked. Ask a project admin for an active key. |
| AUTH_INVALID_TOKEN | 401 | A dashboard session token failed verification. Sign in again. Agents should use an API key, not a session token. |
| AUTH_EXPIRED_TOKEN | 401 | A dashboard session token has expired. Sign in again to get a fresh session. |
| FORBIDDEN_INSUFFICIENT_ROLE | 403 | Your role cannot perform this action. Ask an organization admin for the editor or admin role. |
| PROJECT_ACCESS_DENIED | 403 | The key does not belong to the project you referenced. Use the API key created for that project. |
| PLAN_LIMIT_EXCEEDED | 403 | Your organization has reached its plan's quota. Upgrade the plan in the Billing tab, or contact us. |
| INVALID_JSON_BODY | 400 | The body is not valid JSON. Send Content-Type: application/json with a valid JSON body. |
| INVALID_REQUEST_PAYLOAD | 400 | A 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_PARAMETER | 400 | Fluxix could not tell which project the request is for. Use a project API key, or include projectId in the request body. |
| PROJECT_NOT_FOUND | 404 | No project matches the ID you sent. Check the project ID. |
| AGENT_NOT_FOUND | 404 | No agent matches the ID you sent. Check the agent ID. |
| AUDIT_LOG_NOT_FOUND | 404 | No audit log event matches the ID you sent. Check the event ID in the audit log. |
| CLIENT_CONNECTION_ABORTED | 499 | Your client closed the connection before the response finished. Raise your client timeout for long responses, or use streaming. |
| INPUT_POLICY_VIOLATION | 403 | The 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_BLOCKED | 403 | The 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_BLOCKED | 403 | The 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_FAILED | 401 | No 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_EXCEEDED | 429 | You hit the provider's rate limit. Retry with exponential backoff, or raise your quota with the provider. |
| UPSTREAM_MODEL_NOT_FOUND | 404 | The 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_EXCEEDED | 400 | The 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_REQUEST | 400 | The provider returned 400 for another reason, such as an unsupported parameter. The cause field contains the provider's own message. |
| UPSTREAM_TIMEOUT | 504 | The provider returned 504, or the connection to it timed out. Retry, lower max_tokens, or use streaming for long responses. |
| UPSTREAM_CONNECTION_REFUSED | 502 | Fluxix could not connect to the provider. For local models, check the server is running and reachable at x-provider-base-url. |
| UPSTREAM_SERVICE_UNAVAILABLE | 503 | The provider returned 503: it is down or overloaded. Retry with backoff and check the provider's status page. |
| UPSTREAM_BAD_GATEWAY | Provider's status, or 502 | The 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_STREAM | 502 | A streaming request came back with no data. Check that the model supports streaming, then retry. |
| INTERNAL_SERVER_ERROR | 500 | An unexpected error inside the gateway. Retry once. If it continues, contact us with the requestId from the response. |