# Troubleshooting

Common issues and solutions for API Connections.

## Upload Issues

### File Won’t Upload

- Verify file extension is `.json`, `.yaml`, or `.yml`
- Check file size is under 5MB (all tiers)
- Validate JSON/YAML syntax using an online validator
- Ensure specification follows OpenAPI 3.x or Swagger 2.0 standards

### Too Many Operations

Free Tier limit is 25 operations per catalog. Remove rarely-used endpoints or upgrade to Vendia Pro or Enterprise.

## Authentication Issues

### 401 Unauthorized

- Verify header name is correct (case-sensitive: `Authorization`, `X-API-Key`, etc.)
- Check credential hasn’t expired
- Ensure token format is correct (e.g., `Bearer` followed by space, then token)
- Test credentials directly with `curl` or Postman outside Vendia to verify they work

### 403 Forbidden

- Verify credential has permission to access the endpoint
- Check if API has IP restrictions (Vendia MCP Gateway uses AWS us-east-1)
- Confirm API key or token scope includes the required permissions

## Catalog Visibility Issues

### AI Application Can’t See Catalog

- Verify catalog is enabled in Vendia console
- Check that your AI application is properly [connected to the Vendia MCP Gateway](https://docs.vendia.com/platform/vendia-mcp-server/getting-started)
- Confirm the Vendia MCP Gateway appears in your AI application’s list of active/enabled servers
- Restart your AI application to refresh available tools
- Check MCP server URL is correct in AI application settings
- Review MCP server logs for connection errors

## API Call Failures

### Timeouts or Connection Errors

- Verify API service is running and accessible
- Check Base URL is correct in catalog configuration (must include `https://`)
- Test API directly outside Vendia to confirm it’s reachable

### Incorrect Responses

- Verify Base URL points to correct environment
- Check API version matches specification
- Ensure the API or backend application has the appropriate scopes allowed for invocation
- Review API documentation for changes

## Getting Help

For additional support:

- Review [API Connections Overview](https://docs.vendia.com/platform/vendia-mcp-server/api-connections)
- Check [Authentication and Headers](https://docs.vendia.com/platform/vendia-mcp-server/api-connections/authentication)
- See [Creating API Connections](https://docs.vendia.com/platform/vendia-mcp-server/api-connections/creating-api-connections)
- Contact support at [bd@vendia.com](mailto:bd@vendia.com)