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.

The request was authenticated but access was refused. Confirm that your account is licensed for the data you are requesting. Your Morningstar account manager can confirm what your agreement includes.

You can only request the views in the packages you are licensed for.

• Call the list views endpoint to see the views you can request. See Get View IDs.
• Check the spelling of the viewId. View IDs are lowercase and hyphenated.
• If you expect to have access, contact your Morningstar account manager.

An error occurred on the server. 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.

An upstream service is temporarily unavailable (503.investmentDetailsAsync.040). Wait, and then retry the request.

The response says The Prefer header is required.

• Add the header Prefer: respond-async to requests for investment details.
• Check that the value is exactly respond-async. Any other value is rejected.
• If a utility endpoint, such as delta dates or the list of views, returns an error about the header, remove it from that request.

The response says The {0} parameter is required, and names the missing parameter.

• Check that the body includes both investments and views.
• Check that views with required parameters have them. For example, equity-financials needs reportType and period. See Package-Specific Guides.
• Check the spelling and capitalization of the property names.

The response says The input id does not match the specified idType, or The input idType is not recognized.

• Check that idType is one of performanceId, isin, fundCode, securityId, cusip, msid, tradingSymbol or industryCode, spelled exactly as shown.
• Check that each idType describes the identifier in its id. An entry with no idType is treated as a Morningstar Performance ID.

The response status is 413.

• 413.investmentDetailsAsync.007: a request can include up to 250 investments. Split a larger universe across several requests.
• 413.investmentDetailsAsync.008: a request can include up to 3 views. Split the views across several requests.

See Core Concepts.

The response says that views must be submitted individually and cannot be combined with other views (400.investmentDetailsAsync.019).

• full-look-through-portfolio-holdings and full-portfolio-holdings-month-end-or-quarter-end-most-recent must each be the only view in the request. They can't be combined with each other either.
• equity-financials must also be the only view in the request.
• Make a separate request for each of these views.

See Views.

Date errors have several causes.

• Format. Dates must be yyyy-MM-dd, for example 2025-01-31 (400.investmentDetailsAsync.011 or .032).
• Order. startDate can't be later than endDate (400.investmentDetailsAsync.010).
• Range. The range can be up to 60 months (413.investmentDetailsAsync.009).
• Views with no time series. startDate and endDate aren't valid for a view that returns only the most recent data (400.investmentDetailsAsync.035). Remove the dates for that view.

The response says The input {0} value is not recognized. Please input a valid value (400.investmentDetailsAsync.021 or .031).

• Check the value against the accepted values for the parameter. See API Inputs and the package-specific guide for the view.
• Pass view parameters as arrays, for example "period": ["a"].
• Check that you aren't passing a parameter that belongs to a different view.

For the portfolio holdings views, the accepted values depend on the view and the endpoint.

• In a request for a portfolio holdings view, holdingsView is Full, Top25 or Top10. For full-look-through-portfolio-holdings, the response says only full and top25 are valid (400.investmentDetailsAsync.028).
• For the portfolio holdings dates endpoint, holdingsView is 10, 25 or full, and type is mostRecent, timeSeries or staticDates.
• With type set to timeSeries, frequency is d or m, and startDate and endDate are required. With staticDates, the dates array can have up to 10 dates.

See Full Look Through Portfolio Holdings.

The response says Invalid delta date format (400.investmentDetailsAsync.033), or that the deltaStartTime can't be later than the deltaEndTime (400.investmentDetailsAsync.034).

• Write deltaStartTime and deltaEndTime in UTC, in the format yyyy-MM-ddTHH:mm:ssZ, for example 2025-02-07T19:06:55Z.
• Make sure deltaStartTime isn't later than deltaEndTime.

See Retrieve Delta Dates.

The response says that the viewType isn't valid (400.investmentDetailsAsync.049).

• Omit viewType to use the default, package.
• If you set it, use one of the values that the response lists, spelled exactly as shown.

See API Inputs.

The request was accepted, but you can't retrieve the results.

• Check that you saved the jobId and the status link from the 202 response.
• Check the status of the job with the link, and wait until it is complete before you retrieve the results.
• Use the result ID that the job provides. A job ID isn't a result ID.
• Check that your token is still valid. Request a new one if it has expired.

See Retrieve Investment Details.

The request succeeded, but one of your investments has no data. Investments that couldn't be matched are reported in metadata.messages.

1. Check metadata.messages for the identifier and its idType.
2. Check the identifier for typos.
3. Check that idType matches the identifier.
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 Retrieve Investment Details.

An investment was returned, but the data for a view is missing.

• Check metadata.messages for data points that you aren't entitled to.
• Check the view's parameters. A parameter that applies to a different view is ignored, and a missing required parameter fails the request.
• Check the date range. A time series view returns only the data in the range.
• Check the view definition to see whether the data point exists for the investment's type. See Get View IDs.

• Set languageId to the language you want. The default is ENG.
• Only language-dependent data points change with languageId. The view definition shows which ones depend on language.
• Country-dependent data points use countryId, and the default is USA.

See Get View IDs.

If you don't pass portfolioDate, the most recent holdings data is returned.

• Retrieve the dates that are available with the portfolio holdings dates endpoint, and pass one as portfolioDate.
• Check metadata.portfolioDate in the results to see the date of the data.

See Full Look Through Portfolio Holdings.

If you don't pass deltaStartTime, the API returns the full load.

• Add deltaStartTime to the request.
• Check that the view is equity-financials, since delta loads currently apply to that view only.

See Request Delta Load.

When includeUnchangedData is false, which is the default, each changed row contains only the fields that changed. Set includeUnchangedData to true to get each changed row complete, with all its fields.

See Request Delta Load.

The response gives the error code 413.investmentDetailsAsync.005. Split the request into smaller requests.

• Request fewer investments in each request.
• Request fewer views, or a view with fewer parameters.
• Use a shorter date range for time series views.
• Merge the results in your application.