Documentation Browse docs ☰ Docs / Resources / Troubleshooting guide Private Alpha Troubleshooting guide Common error codes, symptoms, and resolution steps for Gateway, approvals, credentials, and model routing issues.
This page indexes known error codes, symptoms, and resolution steps observed across Chat, Studio, Connected Apps, Model Intelligence, the Gateway, approvals, credentials, and model routing.
Gateway errors Code Meaning Resolution INVALID_REQUESTThe request body failed basic validation (e.g. missing messages array). Check the request format against the chat completions API . MESSAGES_REQUIREDThe chat completions endpoint requires at least one message in the messages array. Add a messages array with at least one entry. SETUP_REQUIREDAn AI provider is not configured for the requested route. Configure a provider API key via the Gateway dashboard or BYOK. PROVIDER_UNAVAILABLEThe upstream AI provider could not complete the request. The request was forwarded to fallback providers if configured. If no fallback succeeded, check provider health in the Gateway dashboard. PROVIDER_NOT_IMPLEMENTEDThe selected provider is known but not yet wired for live execution. Choose a different provider or route. INTERNAL_ERRORUnexpected server error. Retry the request. If it persists, check Gateway server logs.
Authentication and API key errors Code Meaning Resolution missing_api_keyThe request did not include an API key in the Authorization header. Add Authorization: Bearer <your-key> to the request headers. invalid_api_keyThe provided API key is not recognised. Verify the key was created and has not been revoked. Keys are hashed with SHA-256 + salt and cannot be recovered. revoked_api_keyThe API key has been revoked and is no longer valid. Create a new API key in the Gateway dashboard. expired_api_keyThe API key has passed its expiration date. Create a new API key or update the expiration. insufficient_scopeThe key lacks the required scope for the requested operation. Ensure the key has the gateway:invoke scope for chat completions.
Provider credential errors Symptom Likely cause Check Gateway returns SETUP_REQUIRED for a provider Provider API key is not configured (no environment variable and no BYOK credential) Set the provider's environment variable or store a BYOK credential. test_failed credential statusThe stored credential failed a connectivity test Verify the key is valid in the provider's dashboard. Desktop shows "Credential not available" Electron safeStorage is unavailable Use environment variables as fallback.
Approval errors Symptom Likely cause Check Approval request shows stale status The payload hash no longer matches the current state Re-submit the approval request with updated content. Approval request shows blocked status Policy prohibits the action at the configured risk level Review the approval policy configuration. Approval request expired before a decision The expiresAt timeout was reached Create a new request with a longer expiry window.
Model routing errors Symptom Likely cause Check Requested model not available The model is not in the Gateway model catalog or is restricted by provider allowlist Check the model catalog . Provider skipped in routing Circuit breaker open, provider not configured, or blocked by allowlist Check provider health in the Gateway dashboard. Request fails with no fallback All eligible providers are unavailable Verify at least one provider is configured and has a closed circuit breaker.
Chat Symptom Likely cause Check Stream stalls or errors mid-answer Transient provider or network failure Cancel and retry once; if it persists, check status . Signed-out loop / session errors Expired or invalid session Sign out and back in; clear site cookies for chat.upcube.ai if it repeats. Voice session answers VOICE_NOT_CONFIGURED Voice not configured on this deployment Nothing to fix client-side; the deployment names the missing server key. Model behaves unexpectedly Capabilities differ per model Confirm the model selector choice; compare capabilities on Model Intelligence .
Studio Symptom Likely cause Check Workbench unreachable after sign-in Private-alpha enrollment missing Access requires enrollment; see status . Job fails with VALIDATION_ERROR Bad prompt, unknown task, or bad parameters Fix the named field; nothing was reserved or spent. Job lands in an uncertain outcome Provider state could not be confirmed Read the job's recovery steps; check activity before retrying. Empty catalog or missing endpoints Catalog fetch failure This is an error, never an empty result — retry; persistent emptiness is a bug, report it.
Connected Apps and Flow Code Meaning Resolution NEEDS_REAUTHProvider grant expired or revoked upstream Reconnect the connection from settings. MISSING_SCOPE / SCOPE_NOT_GRANTEDAction needs an ungranted scope Grant the named scope or decline the action. APPROVAL_REQUIREDAction needs your approval Approve the exact action, or deny it. APPROVAL_MISMATCH / APPROVAL_EXPIREDApproval no longer matches or timed out Review and approve again. ADMIN_POLICY_BLOCKEDWorkspace admin blocked the action Ask your admin for access. CONNECTION_NOT_FOUNDConnection revoked or never existed Reconnect; pending actions on it will not run. UNKNOWN_OUTCOMECompletion could not be confirmed Check activity before retrying.
Model Intelligence API Symptom Likely cause Check /api/mi/v1/models/:slug answers 404Unknown slug List the index and copy the slug exactly; slugs are case-sensitive. 301 redirect Slug moved Follow the redirect to the canonical slug. 410 removed Model deliberately removed It will not come back under this slug; pick another model. 500 quarantined Model held for review Read the reason; retry later.
See also