Troubleshooting the V connector

This page lists the error codes the Ventur3 MCP connector can return, what each one means, and how to resolve it. Errors fall into three groups depending on where you hit them: connecting (OAuth sign-in), registering a client, and calling the API with an access token.

---

Connecting — OAuth sign-in errors

Returned from the authorization and token endpoints during the OAuth flow. The code arrives as the standard OAuth error parameter.

Error	Meaning	How to resolve
login_required	You requested prompt=none but the user is not signed in.	Retry without prompt=none, or have the user sign in first.
consent_required	You requested prompt=none but the user has not yet granted consent.	Retry with an interactive prompt so the user can approve access.
access_denied	The user declined the consent request.	Nothing to fix technically — the user chose not to connect.
invalid_target	The resource parameter is not one this server issues tokens for.	Request the correct resource identifier for the Ventur3 connector.
unsupported_grant_type	The token request used a grant other than authorization_code or refresh_token.	Use one of the two supported grants.
invalid_grant	At token exchange, the user is no longer permitted to use the connection.	The user must reconnect; their account may have lost access.
invalid_client	The client identifier or its metadata document failed validation.	Check your client metadata document (see below).

403 refusal page (not an OAuth error). If the signed-in user is not eligible to use the connector, the authorize endpoint shows a 403 page instead of an OAuth error. Reasons include: the account is impersonating another user, is not a planner account, has no organisation, has an unconfirmed email, is locked out, or the organisation is blocked. These are account-state issues — the user should contact their administrator.

---

Registering a client — Dynamic Client Registration (RFC 7591)

Returned from the registration endpoint as HTTP 400 with a JSON body of { "error": ..., "error_description": ... }. A successful registration returns HTTP 201 Created.

Error	Meaning	How to resolve
invalid_redirect_uri	A redirect URI is missing, malformed, not on the allowed list, or you supplied more than the permitted number.	Provide valid redirect URIs that meet the connector's rules; keep the count within the limit.
invalid_client_metadata	The registration body is invalid: too large, not valid JSON, not a JSON object, or a field (grant_types, response_types, client_name, token_endpoint_auth_method) is missing or has a disallowed value.	Ensure the request includes authorization_code in grant_types, code in response_types, a string client_name, and a supported auth method.

Client ID Metadata Documents

If you identify your client with a metadata-document URL rather than dynamic registration, a validation failure surfaces during authorization as invalid_client. Common causes:

• The client_id URL is not https, is too long, contains a query/fragment/whitespace, embeds user info, uses an IP address or non-default port, or has a missing or dot-segment path.
• The fetched document is not valid JSON or not a JSON object, its client_id does not match the URL it was fetched from, or it contains a client_secret or a non-none authentication method.
• The document could not be fetched: the URL redirected, returned a non-200 status, was too large, timed out, or the address was refused.

---

Calling the API — access-token and runtime errors

Returned once you are making authenticated requests with a bearer token.

Authentication and authorization

Status	Error	Meaning	How to resolve
401	invalid_token	The access token was rejected. The error_description says why: token expired, wrong audience, wrong issuer, not an access token, or a bad signature.	Refresh the access token; if that fails, reconnect.
401	invalid_token	The connection itself is no longer valid: the token names no user, the user no longer exists, the connection was revoked or expired, or the account can no longer use the connector.	Reconnect the Ventur3 connector.
403	insufficient_scope	The token is valid but lacks the required read scope.	Request the connector's read scope during authorization.

Operational errors

Status	Error	Meaning	How to resolve
503	mcp_disabled	The connector is temporarily unavailable (maintenance). A Retry-After header indicates when to retry.	Wait and retry after the indicated delay.
403	origin_not_allowed	The request carried an Origin header that is not permitted (browser-security protection).	Do not send a disallowed Origin; call the API from a server-side context.
429	(none)	Rate limit exceeded. A Retry-After header indicates when to retry.	Back off and retry after the indicated delay; reduce request volume.

Tool-call errors

Some failures are returned as a successful HTTP 200 response whose tool result is flagged as an error, so the model can read and act on the message. These include:

• Connection no longer authorised — reconnect the connector and try again.
• Result too large — narrow your query or request results in smaller pages.
• Unknown tool or invalid arguments — check the tool name and argument shape.

---

Quick reference

• HTTP statuses: 201 (registration success), 400 (registration error), 401, 403, 429, 503
• OAuth sign-in: login_required, consent_required, access_denied, invalid_target, unsupported_grant_type, invalid_grant, invalid_client
• Registration: invalid_redirect_uri, invalid_client_metadata
• Access token: invalid_token, insufficient_scope
• Operational: mcp_disabled, origin_not_allowed