--- title: "Troubleshooting" description: "Diagnose and fix common Equities Screener API problems, from authentication and invalid requests to empty results and missing data points." url: "https://developer-beta.morningstar.com/equities-screener-api/troubleshooting" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~VHJvdWJsZXNob290aW5nIHwgRXF1aXRpZXMgU2NyZWVuZXIgQVBJ,description_~RGlhZ25vc2UgYW5kIGZpeCBjb21tb24gRXF1aXRpZXMgU2NyZWVuZXIgQVBJIHByb2JsZW1zLCBmcm9tIGF1dGhlbnRpY2F0aW9uIGFuZCBpbnZhbGlkIHJlcXVlc3RzIHRvIGVtcHR5IHJlc3VsdHMgYW5kIG1pc3NpbmcgZGF0YSBwb2ludHMu,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9lcXVpdGllcy1zY3JlZW5lci1hcGkvdHJvdWJsZXNob290aW5nIg,s_4n0JWNoFnHQNYN4q.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) # Equities Screener API Powerful, criteria-based screening using flexible filtering logic. # Troubleshooting [View Markdown](https://developer-beta.morningstar.com/equities-screener-api/troubleshooting.md)[Download Markdown](https://developer-beta.morningstar.com/equities-screener-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/equities-screener-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` on `POST` requests. - The request includes a `scope` that contains the exchange code data point. - Every data point name is valid, and there are no more than 100 of them. - Each filter uses an operator that the data point supports. - Dates are in `yyyy-MM-dd` format, numbers have no quotation marks, and operators are in lowercase. - A request uses 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.screener.005", "message": "Invalid dataPoint names {0}. Provide valid values.", "requestId": "5c2ad24c-964b-4f9b-9d9e-26b7bdb915d9" } ``` 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/equities-screener-api/work-with-results#handle-warnings). Use the `errorCode` to look up the issue on the [Errors](https://developer-beta.morningstar.com/equities-screener-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). --- 500 Internal Server Error 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. --- ## [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/equities-screener-api/api-inputs) reference. - If you can't find the cause, contact support and include the `requestId`. --- Invalid Data Point Names The response says `Invalid dataPoint names` and gives the error code `400.screener.005`. - Check each name in `dataPoints`, `query`, `scope` and `sort` for typos. Names have the format `dataGroup.fieldName`. - Retrieve the valid names from the data points endpoint, and copy them from there. See [Explore Data Points](https://developer-beta.morningstar.com/equities-screener-api/explore-data-points). --- Invalid Sort Option The response says `Please provide valid sort option` and gives the error code `400.screener.006`. - Check that `dataPoint` is a valid data point name. - Check that the data point is sortable. Its metadata shows this. - Check that the data point is also in the `dataPoints` array. - Check that `orderBy` is `asc` or `desc`. --- A Filter Isn't Accepted A filter can be rejected when the operator or the value doesn't suit the data point. - Check the data point's metadata. It lists the operators it supports, and a range comparison isn't available for every data point. - Match the value format to the data type. Write numbers without quotation marks, booleans as `true` or `false`, and dates as `yyyy-MM-dd` strings. - Use lowercase operator names, such as `and`, `or`, `gt` and `lte`. - Give a list at least one value, and keep all its values to one type. - In a comparison filter, use only `gt`, `gte`, `lt` and `lte`. See [Operators](https://developer-beta.morningstar.com/equities-screener-api/operators). --- Fuzzy Search Returns an Error Fuzzy search has restrictions. - It works only on string data points that support it. If you set `fuzzy` to `true` on one that doesn't, the request returns an error. - It works only as an equality filter. - The search text must be at least 3 characters. See [Equality and Text Filters](https://developer-beta.morningstar.com/equities-screener-api/equality-and-text-filters#use-fuzzy-search). --- Scope Is Missing or Invalid A request must include a `scope`. - Check that the `scope` property is present. - Check that it contains the exchange code data point, `shareClassInformation.exchangeCode`. - If the scope is a compound filter, check that every branch contains the exchange code. A branch without it isn't valid. See [Screen Equities](https://developer-beta.morningstar.com/equities-screener-api/screen-equities#step-1-define-the-scope). --- Too Many Data Points A request can include a maximum of 100 data points. If you need more, split them across several requests, and match the results using the performance ID, which is returned in every match. --- Language or Currency Isn't Accepted - `languageId` must be one of the supported language codes, such as `ENG` or `FRE`. See [API Inputs](https://developer-beta.morningstar.com/equities-screener-api/api-inputs#languageid). - `currencyId` must be an ISO 4217 currency code, such as `USD` or `EUR`. - Set them only when you request language-dependent or currency-dependent data points. --- Pagination Token Is Rejected - Use either `paginationTokenNext` or `paginationTokenPrevious` in a request, not both. - Pass the token exactly as it was returned in the previous response, with no changes. - Take the token from the response to the same request. A token from a different request may not work. See [Work with Results](https://developer-beta.morningstar.com/equities-screener-api/work-with-results#use-the-result-count-and-pagination-tokens). --- ## [Unexpected Results](#unexpected-results) No Results Are Returned The request succeeded but `investments` is empty. - Check the scope. A scope that is too narrow, or an exchange code that doesn't match, returns nothing. - Check the filters. Conditions in an `and` filter must all match, so two that can't both be true return nothing. - Check that values match the data. Symbols, codes and identifiers must match exactly. - Check whether the investments are in your entitled universe. - Try removing conditions one at a time to find which one excludes everything. --- Too Many Results Are Returned - If you omit `query`, the screen returns everything in the scope. - An `or` filter returns an investment that matches any condition, so it returns more than `and`. Check that you used the operator you meant. - Add conditions to narrow the results, or a more specific scope. --- A Date or Number Filter Misses the Boundary Value `gt` and `lt` are exclusive, so an investment whose value equals the limit isn't matched. Use `gte` or `lte` to include the limit. ```json "marketCapital.asOfDate": { "gte": "2024-01-01", "lte": "2024-12-31" } ``` See [Comparison Filters](https://developer-beta.morningstar.com/equities-screener-api/comparison-filters). --- A Nested Filter Doesn't Behave as Expected - Read the filter from the outermost operator inward, and check that each array holds the conditions you intended. - Check the brackets. A condition in the wrong array changes the logic. - Remember that `not` excludes investments that match any condition in its array. - Use lowercase operator names. See [Compound Filters](https://developer-beta.morningstar.com/equities-screener-api/compound-filters). --- A Data Point Is Missing From an Investment The investment 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/equities-screener-api/work-with-results#handle-warnings). --- I Can't Retrieve All the Results Results are returned in pages of up to 50. - Compare `metadata.totalCount` with the number of investments you have received. - Send the same request again with `metadata.paginationTokenNext` in `pagination.paginationTokenNext`, until a response has no next token. - You can't raise the page size above 50. See [Work with Results](https://developer-beta.morningstar.com/equities-screener-api/work-with-results#use-the-result-count-and-pagination-tokens). --- Results Aren't in the Order I Expected - If you don't set `sort`, results are in ascending performance ID order. - `sort` entries are applied in order, so put the most important sort first. - Check that `orderBy` is `asc` or `desc`. The default is `asc`. - The sorted data point must also be in `dataPoints`. --- Values Are in an Unexpected Currency or Language - Currency-dependent data points are returned in the currency in `currencyId`. The default is `USD`. - Language-dependent data points are returned in the language in `languageId`. The default is `ENG`. - The metadata for each data point shows whether it is currency-dependent or language-dependent. ## [Still Stuck?](#still-stuck) - Check the [Errors](https://developer-beta.morningstar.com/equities-screener-api/error-messages) page for the full list of error codes. - Browse the [FAQs](https://developer-beta.morningstar.com/equities-screener-api/faqs). - Compare your request with the examples in [Example Screens](https://developer-beta.morningstar.com/equities-screener-api/example-screens). - If you contact support, include the `requestId` from the response.