--- title: "Troubleshooting" description: "Diagnose and fix common Universe API problems, from invalid filters to empty results and pagination tokens that are rejected." url: "https://developer-beta.morningstar.com/universe-api/troubleshooting" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~VHJvdWJsZXNob290aW5nIHwgVW5pdmVyc2UgQVBJ,description_~RGlhZ25vc2UgYW5kIGZpeCBjb21tb24gVW5pdmVyc2UgQVBJIHByb2JsZW1zLCBmcm9tIGludmFsaWQgZmlsdGVycyB0byBlbXB0eSByZXN1bHRzIGFuZCBwYWdpbmF0aW9uIHRva2VucyB0aGF0IGFyZSByZWplY3RlZC4,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii91bml2ZXJzZS1hcGkvdHJvdWJsZXNob290aW5nIg,s_oOa8jhrM8hDHK-6y.png" --- - [APIs](https://developer-beta.morningstar.com/apis) - [API Catalog](https://developer-beta.morningstar.com/api-catalog) - [API Assistant MCP Server](https://developer-beta.morningstar.com/api-assistant-mcp) - [Guides](https://developer-beta.morningstar.com/api-guides) - [Trial Access](https://developer-beta.morningstar.com/trial-access) # Universe API Retrieve investment identifiers in your entitled universe. # Troubleshooting [View Markdown](https://developer-beta.morningstar.com/universe-api/troubleshooting.md)[Download Markdown](https://developer-beta.morningstar.com/universe-api/troubleshooting.md) Use this page to diagnose a failed request or a response that doesn't contain what you expected. Each issue lists the likely causes and how to fix them. For the meaning of a specific error code, see [Error Messages](https://developer-beta.morningstar.com/universe-api/error-messages). ## [Before You Start](#before-you-start) Most problems can be traced to one of the following. Check them first. - The `Authorization` header contains `Bearer {token}`, with a token less than 60 minutes old. - The request has a primary filter, if you expect investments in the response. - The filters belong to the investment type. `exchangeCode` is for equities, and `countryAvailableForSaleCode` and `domicileCode` are for managed investments, which also need `source=managedInvestments`. - Secondary filters are used with a primary filter, and their values are accepted. See [Filter Values](https://developer-beta.morningstar.com/universe-api/filter-values). - A request uses at most one primary filter, and at most one pagination token. ## [Reading an Error Response](#reading-an-error-response) A failed request returns a `statusCode`, an `errorCode`, a `message` and a `requestId`. The `message` describes the problem. ```json { "statusCode": 400, "errorCode": "400.investmentDetails.020", "message": "Invalid source input for domicileCode", "requestId": "539d62a5-3586-4070-965e-0f7f64712d79" } ``` Use the `errorCode` to look up the issue on the [Error Messages](https://developer-beta.morningstar.com/universe-api/error-messages) page. Keep the `requestId` in case you need to contact support. ## [Authentication and Access](#authentication-and-access) 401 Unauthorized The token is missing, invalid or expired. - Check that the `Authorization` header is present and uses the format `Bearer {token}`. - Tokens expire after 60 minutes. Request a new token from `POST /token/oauth`, then retry the request. - In jobs that page through a large universe, refresh the token before it expires, and retry any request that returns `401` after refreshing. See [Authentication](https://developer-beta.morningstar.com/api-authentication). --- ## [Request Errors](#request-errors) 400 Bad Request The request is invalid. The `message` in the response describes the problem. - Read the `message` and `errorCode`, then find the parameter it names. - Check the parameters against the [API Inputs](https://developer-beta.morningstar.com/universe-api/api-inputs) reference. - If you can't find the cause, contact support and include the `requestId`. --- Invalid Source Input The response says `Invalid source input for` and names a parameter, for example `domicileCode`. The parameter doesn't belong to the investment type of the request. - `exchangeCode` is the primary filter for equities. Don't use it with `source=managedInvestments`. - `countryAvailableForSaleCode` and `domicileCode` are primary filters for managed investments. Set `source=managedInvestments` when you use them. The default `source` is `equities`. - Secondary filters belong to one investment type too. See [Get Your Universe](https://developer-beta.morningstar.com/universe-api/get-your-universe#step-2-filter-the-universe). --- Unknown Universe Parameter The response says `The Unknown universe Parameter`. - Check the spelling of the `universe` value. It must be the name of a custom universe that was set up for your account. - Check that you are using the right `source`. A custom universe is for either equities or managed investments. - If you don't know the names of your custom universes, contact your Morningstar account manager. See [Get Your Universe](https://developer-beta.morningstar.com/universe-api/get-your-universe#step-3-use-a-custom-universe). --- A Filter Value Isn't Accepted A filter can be rejected when its value isn't one that the API accepts. - Use the codes in [Filter Values](https://developer-beta.morningstar.com/universe-api/filter-values) for `securityType`, `shareClassInformationInvestmentType`, `investmentType` and `fundLegalStructureName`. - Use an exchange code from your entitlements for `exchangeCode`, and 3-character ISO 3166-1 country codes for `countryAvailableForSaleCode` and `domicileCode`. - Check that the value is in your entitlements. See [Get Your Universe](https://developer-beta.morningstar.com/universe-api/get-your-universe#step-1-get-your-entitlements). --- Primary and Secondary Filters Are Mixed Up - A primary filter is required, and a request can use only one. Don't send `countryAvailableForSaleCode` and `domicileCode` together. - Secondary filters can't be used without a primary filter. - Secondary filters narrow the primary filter. Don't use one in place of it. See [Get Your Universe](https://developer-beta.morningstar.com/universe-api/get-your-universe#step-2-filter-the-universe). --- The Page Size Is Rejected `pageSize` must be a whole number from 1 to 50. The default is 50, so you can leave it out. --- A Pagination Token Is Rejected - Pass the token exactly as it was returned, with no changes. - Use either `paginationTokenNext` or `paginationTokenPrevious` in a request, not both. - Keep all the other parameters the same as in the request that returned the token. See [Work with Results](https://developer-beta.morningstar.com/universe-api/work-with-results#page-through-the-results). --- ## [Unexpected Results](#unexpected-results) No Investments Are Returned The request succeeded but `investments` is empty. - If you sent no primary filter, the response lists your entitlements instead of investments. Add a primary filter. See [Work with Results](https://developer-beta.morningstar.com/universe-api/work-with-results#entitlements-response). - Check that the filter value is in your entitlements. A value that you aren't entitled to returns nothing. - Check that secondary filters aren't too narrow. Remove them one at a time to find out which one excludes everything. - Check `source`. A managed investments filter returns nothing for equities. --- There Are Fewer Investments Than I Expected - Your universe is limited to your entitlements, so it can be smaller than the whole of the Morningstar universe. - Secondary filters narrow the results. - A custom universe is a subset of your entitled universe. - Check that you retrieved every page. Keep requesting pages until a response has no `paginationTokenNext`. --- Investments Are Missing or Repeated Across Pages This happens when the filters change between requests. - Keep every parameter except the token the same across the requests for a universe. - Don't change `pageSize` or `source` part of the way through. - Start again from the first page if you have changed a filter. See [Work with Results](https://developer-beta.morningstar.com/universe-api/work-with-results#page-through-the-results). --- I Can't Find the Performance ID for a Managed Investment For managed investments, the `identifiers` object can contain a different identifier from the performance ID. The performance ID is also in the `basicReference` data group, as `basicReference.performanceId`. See [Work with Results](https://developer-beta.morningstar.com/universe-api/work-with-results).