Errors and troubleshooting

This page describes the app's error messages, their cause and the solution. Each message shows a "?" link to the matching section.

Account errors

Session expired (UNAUTHENTICATED)

Cause. Your session has expired or is no longer valid, for example after a password change on another device.

Solution. Sign in again.

Incorrect email or password (INVALID_CREDENTIALS)

Cause. The email or password you entered does not match any account.

Solution. Check what you typed. If you forgot it, use "Forgot password?".

Too many attempts (ACCOUNT_LOCKED)

Cause. After 5 failed sign-in attempts, the account is locked for 15 minutes.

Solution. Wait 15 minutes, then try again with the right password, or reset it.

Email not verified (EMAIL_NOT_VERIFIED)

Cause. The account's email address has not been verified.

Solution. Open the verification link received by email (valid for 24 hours). If it has expired or never arrived, sign in and click "Resend the link".

Email already in use (EMAIL_TAKEN)

Cause. The address entered at sign-up or when changing your email already belongs to another account.

Solution. At sign-up, click "Sign in", or "Forgot password?" if you do not remember the password. When changing your email, choose another address. See Email.

Invalid or expired link (TOKEN_INVALID)

Cause. The link received by email has already been used or has expired. Links are valid for 1 hour (welcome, reset) or 24 hours (verification, email change).

Solution. Request a new link, for example with "Forgot password?".

Server and plan errors

Workspace suspended (WORKSPACE_SUSPENDED)

Cause. Your workspace is suspended: access is restricted and MCP calls are refused.

Solution. Contact the Voozeo team to learn the reason and restore access.

Not found (NOT_FOUND)

Cause. The requested item does not exist or has been deleted, for example a server deleted in another tab.

Solution. Go back to the server list and refresh the page.

Plan limit reached (PLAN_LIMIT_REACHED)

Cause. You have reached a limit of your plan: number of servers, active tools, document text per server, or 1,000 documents. A plan with lower limits than your current usage deletes nothing: it only blocks new creations.

Solution. Delete or disable what you no longer need, then try again. See Quotas and plans. A plan with higher limits can be requested from the "Plans" screen: the "Upgrade" button shown next to the message opens the request form.

Monthly quota reached (QUOTA_EXCEEDED)

Cause. You have used up your MCP calls for the month, sandbox included.

Solution. Wait for the 1st of the next month (UTC). See When the quota is reached.

Plan request already pending (REQUEST_PENDING)

Cause. You already have a plan request waiting for a decision.

Solution. Wait for Voozeo's answer, or cancel the request from the banner of the "Plans" screen and send a new one. See Requesting a plan.

Too many requests (RATE_LIMITED)

Cause. You sent too many plan requests in 24 hours, or too many requests in a short time.

Solution. Wait a little and try again. See Requesting a plan.

Upload no longer pending (CONFLICT)

Cause. The upload in progress, for example a server icon, was replaced or is no longer pending. The same code is returned when you try to regenerate the MCP key of a server whose target API uses OAuth 2.0: such a server has no key.

Solution. Start the upload again. For an OAuth server, connect the AI with OAuth instead (see Servers using OAuth).

OAuth connection required (OAUTH_REQUIRED)

Cause. In the sandbox, you ran an API tool of a server whose target API uses OAuth 2.0. This tool needs the token of a person signed in at the provider, which only an AI connected with OAuth has. Nothing was called and the quota is unchanged.

Solution. Test the tool from your AI connected with OAuth (see OAuth servers). Document tools stay testable in the sandbox.

Forwarded credential required (CREDENTIAL_REQUIRED)

Cause. In the sandbox, you ran an API tool of a server whose target API uses "Forwarded by caller" without entering the "Forwarded credential". Nothing was called and the quota is unchanged.

Solution. Enter the credential your API expects in the field of the "Test" tab. See Per-user credentials with an OAuth gateway.

Invalid image (INVALID_IMAGE)

Cause. The icon is empty, truncated or contains forbidden content (SVG).

Solution. Export the image again or use a PNG. Accepted formats are PNG, JPEG, WEBP or SVG, 256 KB at most.

Import errors

Unsupported OpenAPI version (UNSUPPORTED_SPEC_VERSION)

Cause. The document declares a version other than OpenAPI 3.0.x or 3.1.x, for example Swagger 2.0.

Solution. Convert the specification to OpenAPI 3.0 or 3.1, then import it again. See Accepted formats.

Invalid OpenAPI document (INVALID_SPEC)

Cause. The file is empty, it is neither valid JSON nor valid YAML, it has no paths section, it contains no operation, or it contains more than 1,000.

Solution. Validate the file in an OpenAPI editor, fix it, then import it again. The detail of the problem is shown on the failed source.

Processing took too long (INGESTION_TIMEOUT)

Cause. Analyzing the file took more than 28 seconds.

Solution. Try a smaller file, or split a large document into several files.

Too many documents to index (SOURCE_MEMORY_LIMIT)

Cause. The total text of the server's documents is larger than what Voozeo can index in one go with the current capacity. The source is marked "Failed" and nothing is published: the documents that were already ready keep working.

Solution. Remove some documents, then add the new one again. If you need this volume, contact the Voozeo team.

File too large (FILE_TOO_LARGE)

Cause. The file exceeds the maximum size: 5 MB for an OpenAPI specification, 10 MB per document.

Solution. Reduce the file or split it. See Sizes and limits.

Unsupported file type (UNSUPPORTED_FILE_TYPE)

Cause. The extension is not accepted, or the content does not match the extension (for example a .pdf file that is not a PDF).

Solution. Use a valid PDF, Word (.docx), Markdown (.md, .markdown) or text (.txt) file.

No text extracted (NO_TEXT_EXTRACTED)

Cause. The document contains no usable text, typically a scanned PDF: there is no optical character recognition (OCR).

Solution. Provide a version with selectable text. See Scanned PDF.

URL not allowed (UNSAFE_URL)

Cause. The import URL is not HTTPS or points to a non-public address (internal network, local address).

Solution. Use a public HTTPS URL, for example https://api.example.com/openapi.json, or import the file directly.

Remote file not downloaded (UPSTREAM_FETCH_FAILED)

Cause. The download failed: the remote server answered with something other than 2xx, or did not answer within 10 seconds.

Solution. Check that the URL opens without authentication in a browser, or download the file and import it. See Import from a URL.

On the AI side

These cases show up in your AI client, not in the app. See also Connection troubleshooting.

MCP key refused (401)

Cause. The key is missing, invalid, has been regenerated since, or belongs to another server.

Solution. Copy the URL or configuration again from the "Connection" tab. If the key was lost, regenerate it in the "Connection" tab: the old one stops working immediately.

Sign-in required (401, OAuth)

Cause. On a server whose target API uses OAuth 2.0, the AI's connection is no longer valid: it expired or was revoked (by you, by a change of the OAuth settings, or at the provider), the provider refused to renew it, or the AI was not used for 30 days and its registration expired. An MCP key is also refused on such a server.

Solution. Most AIs offer to sign in again on their own: follow the browser page. If the AI keeps failing, remove the server from the AI and add it again with its URL (see Servers using OAuth).

Server disabled or workspace suspended (403)

Cause. The server is not active (draft or disabled: "Server is not active"), or the workspace is suspended ("Workspace is suspended").

Solution. Enable the server, or add a source first so it moves from draft to active. See Server statuses.

Quota reached on the AI side

Cause. The MCP calls of the month are used up. The tool answers with a tool error: Monthly quota reached. Upgrade your plan: followed by a link to the Voozeo pricing page.

Solution. Wait for the 1st of the next month (UTC). See Quotas and plans.

Unknown tool

Cause. The AI called a tool name that does not exist on the server, or that is disabled, often a typo or an outdated tool list. The AI receives the message "Unknown tool: " followed by the name and your API is not called. The call is logged with the step "Unknown tool" and the requested name in its details; it does not count toward the quota.

Solution. Check the tool name in the "Tools" tab and that the tool is enabled. If the name is right, ask the AI to refresh its tool list (reconnect the server). The Top errors block shows the names requested most often.

Missing parameter

Cause. The AI called a tool without a required parameter. It receives "Missing required parameter(s): id, body" (the missing names) and your API is not called. The call is logged with the step "Invalid input" and counts toward the quota.

Solution. Check in the "Tools" tab which parameters are required, and that their descriptions tell the AI what to send. The sandbox shows the same message.

Other errors

Invalid fields (VALIDATION_ERROR)

Cause. One or more form fields do not follow the expected rules (length, format, required value).

Solution. Fix the highlighted fields, then submit again. Example: a server name must be 1 to 60 characters long.

Unexpected error (INTERNAL_ERROR)

Cause. An unexpected error occurred on the Voozeo side.

Solution. Try again in a moment. If it persists, contact the Voozeo team and say what you were doing.

Two other messages have no code to look up. "Can't reach Voozeo" means your internet connection is down or unstable: check it, then try again. "Too many requests" means you sent many requests in a short time: wait a moment, then try again.