--- title: "Troubleshooting" description: "Diagnose and fix common Investment List API problems, from authentication and invalid requests to missing rows and data points." url: "https://developer-beta.morningstar.com/investment-list-api/troubleshooting" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~VHJvdWJsZXNob290aW5nIHwgSW52ZXN0bWVudCBMaXN0IEFQSQ,description_~RGlhZ25vc2UgYW5kIGZpeCBjb21tb24gSW52ZXN0bWVudCBMaXN0IEFQSSBwcm9ibGVtcywgZnJvbSBhdXRoZW50aWNhdGlvbiBhbmQgaW52YWxpZCByZXF1ZXN0cyB0byBtaXNzaW5nIHJvd3MgYW5kIGRhdGEgcG9pbnRzLg,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9pbnZlc3RtZW50LWxpc3QtYXBpL3Ryb3VibGVzaG9vdGluZyI,s_ElM67f7_B7AktxDf.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) # Investment List API Build the Investment List API into your digital experience for quick investment and earnings summaries. # Troubleshooting [View Markdown](https://developer-beta.morningstar.com/investment-list-api/troubleshooting.md)[Download Markdown](https://developer-beta.morningstar.com/investment-list-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 [Errors](https://developer-beta.morningstar.com/investment-list-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 `Content-Type` header is `application/json`, and the body is valid JSON. - The body includes both `investments` and `dataPoints`. - There are no more than 100 investments, 50 data points and 2 sort fields. - Each `idType` matches its `id`, and an entry with no `idType` holds a Morningstar Performance ID. - Every data point name is valid, and every sort data point is also in `dataPoints`. ## [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.investmentList.004", "message": "Invalid datapoints companyGrade.profitaityGrade, legalName. Please send the name correctly", "requestId": "e08f8bbc-f5f5-4587-a65a-41e7d056a50c" } ``` A request can also succeed and still carry warnings. Always check `metadata.messages` in a successful response. See [Work with Results](https://developer-beta.morningstar.com/investment-list-api/work-with-results#handle-warnings). Use the `errorCode` to look up the issue on the [Errors](https://developer-beta.morningstar.com/investment-list-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 long-running jobs, refresh the token before it expires, and retry any request that returns `401` after refreshing. See [Authentication](https://developer-beta.morningstar.com/api-authentication). --- 403 Forbidden The request was authenticated but access was refused. Confirm that your account is licensed for the Investment List API. Your Morningstar account manager can confirm what your agreement includes. --- 500 Internal Server Error An error occurred on the server, for example `Error calling Investment Service Api`. Error details are not included in the response. Check that the request body is valid JSON, then retry the request. If the error persists, contact Morningstar support with the `requestId` and the time of the request. --- ## [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 property it names. - Check the properties against the [API Inputs](https://developer-beta.morningstar.com/investment-list-api/api-inputs) reference. - If you can't find the cause, contact support and include the `requestId`. --- A Required Parameter Is Missing The response says `The {0} parameter is required` and gives the error code `400.investmentList.002`. The message names the missing parameter, for example `Investments`. - Check that the body includes both `investments` and `dataPoints`. - Check the spelling and capitalization of the property names, and that each is an array. --- Too Many Investments or Data Points The response says `The number of {0} exceeds limit` and gives the error code `400.investmentList.003`. The message names the limit that was exceeded. - A request can include from 1 to 100 investments. Split larger lists across several requests. - A request can include up to 50 data points. If you need more columns, make several requests and join the rows on `performanceId`. - A request can include up to 2 sort fields. See [Request an Investment List](https://developer-beta.morningstar.com/investment-list-api/request-an-investment-list#request-limits). --- Invalid Data Point Names The response says `Invalid datapoints` and gives the error code `400.investmentList.004`. The message lists the names that weren't accepted. - Check each name in `dataPoints` for typos. Names have the format `dataGroup.fieldName`, so a bare field name such as `legalName` isn't valid. - Retrieve the valid names from the data points endpoint, and copy them from there. See [Explore Data Points](https://developer-beta.morningstar.com/investment-list-api/explore-data-points). --- Sort Options Are Rejected Sort errors have three causes. - **Missing values (`400.investmentList.005`).** Each `sort` entry needs both a `dataPoint` and an `orderBy`. - **Invalid direction (`400.investmentList.006`).** `orderBy` must be `asc` or `desc`. - **Mismatched data point (`400.investmentList.007`).** The `dataPoint` in `sort` must also be in the `dataPoints` array. Add it to `dataPoints`, or sort by a data point you are already requesting. See [Request an Investment List](https://developer-beta.morningstar.com/investment-list-api/request-an-investment-list#step-3-set-sort-preferences). --- Invalid JSON The response gives the error code `400.investmentList.009` or `400.investmentList.010`, and says to provide the request input in valid JSON. - Check for missing commas, unclosed brackets and braces, and trailing commas. - Check that keys and string values use double quotation marks. - Check that numbers and booleans have no quotation marks. - Check that `Content-Type` is `application/json`. A JSON validator can help to find the problem. --- Identifier Type Not Supported The response gives the error code `400.investmentList.008` and says that an `IdType` isn't supported. - Set `idType` to one of `performanceId`, `isin`, `fundCode`, `securityId`, `cusip`, `msid` or `tradingSymbol`, spelled exactly as shown. - Check that each `idType` matches the identifier in its `id`. See [Request an Investment List](https://developer-beta.morningstar.com/investment-list-api/request-an-investment-list#step-1-specify-investments). --- ## [Unexpected Results](#unexpected-results) An Investment Is Missing From the Response The request succeeded but one of your investments has no row. Unmatched identifiers are listed in `metadata.messages`, and the `investments` array contains only the investments that matched. 1. Check `metadata.messages` for the identifier and its `idType`. 2. Check the identifier for typos. 3. Check that `idType` matches the identifier. An entry with no `idType` is treated as a Morningstar Performance ID. 4. Check whether lookup details, such as `domicile` or `exchangeCountry`, are excluding the investment. 5. Try a different identifier for the same investment. The Morningstar Performance ID is the most precise. See [Work with Results](https://developer-beta.morningstar.com/investment-list-api/work-with-results#identifiers-that-couldnt-be-matched). --- The Wrong Investment Was Returned An identifier such as a trading symbol can match more than one investment. - Add lookup details to the entry, such as `exchangeCountry`, `domicile`, `baseCurrency` or `exchangeId`, to narrow the match. - Use a Performance ID, which identifies a single investment. - Add a data point such as `basicReference.name` or `instrumentIdentifiers.isin` to the request, to check which investment each row is for. See [Request an Investment List](https://developer-beta.morningstar.com/investment-list-api/request-an-investment-list#narrow-the-lookup). --- A Data Point Is Missing From a Row The row was returned, but a data point you requested isn't in it. - Check `metadata.messages`. If you aren't entitled to the data point, a warning lists it, with the error code `403`. - Remove data points that you aren't entitled to from `dataPoints`, or contact your Morningstar account manager about access. See [Work with Results](https://developer-beta.morningstar.com/investment-list-api/work-with-results#handle-warnings). --- I Can't Match Rows to My Input The rows don't repeat the identifiers you sent, and an investment that can't be matched has no row. - Match rows using `performanceId`, not the position of the row. - If you sent ISINs, trading symbols or other identifiers, add a data point that returns that identifier, for example `basicReference.isin` or `instrumentIdentifiers.isin`. - Check `metadata.messages` for identifiers that returned no row. See [Work with Results](https://developer-beta.morningstar.com/investment-list-api/work-with-results#match-rows-to-your-request). --- Rows Aren't in the Order I Expected - If you don't set `sort`, rows are in ascending performance ID order. - `sort` entries are applied in order, so put the most important sort first. You can use at most 2. - Check that `orderBy` is `asc` or `desc`. The default is `asc`. - The sorted data point must also be in `dataPoints`. --- Numbers Look Like Text Some numeric values can be returned as strings, for example `"-95.000000"`. Convert them to numbers in your application before you calculate with them or sort them. A missing value is returned as null, or the data point is left out of the row. Handle both. --- Language or Currency Isn't What I Expected The request has optional `languageId` and `currencyId` properties that set the language and currency of the results. - Check that you set them, and that the values are accepted. See [API Inputs](https://developer-beta.morningstar.com/investment-list-api/api-inputs#languageid). - Check whether the data point you are reading depends on a language or a currency. ## [Still Stuck?](#still-stuck) - Check the [Errors](https://developer-beta.morningstar.com/investment-list-api/error-messages) page for the full list of error codes. - Browse the [FAQs](https://developer-beta.morningstar.com/investment-list-api/faqs). - Compare your request with the examples in [Example Lists](https://developer-beta.morningstar.com/investment-list-api/example-lists). - If you contact support, include the `requestId` from the response.