Troubleshooting the ENERGY STAR API

In IBM® Envizi ESG Suite, if the web service API fails to upload data or obtain a valid ENERGY STAR score, review possible issues and causes.

ENERGY STAR Portfolio Manager error code

ENERGY STAR Portfolio Manager might return the following error code message:
Please select your property's primary function (Error -200)
The code indicates either that the property’s primary function has not been sent to Portfolio Manager, or ENERGY STAR Portfolio Manager is not able to determine the primary function of the property based on the data that has been supplied. Envizi determines the primary function of a property by looking at property use with the highest gross floor area number from all property use details accounts in the location. Check whether all the property use details accounts have records that cover the API sync end period. For example, a data sync of 12 months ending in September 2023 requires at least one property use details record covering the month of September 2023.

Common data issues

Has an entity item been deleted in ENERGY STAR Portfolio Manager?
If an entity item such as a meter is deleted in ENERGY STAR Portfolio Manager, you must delete the corresponding ID mapping record in the ENERGY STAR and Envizi ID Mapping page to avoid API data sync errors.
Is utility data available for the specified 12 months period?
The ENERGY STAR score is based on a 12-month period so if data is missing within the 12 month period in any of the accounts, you might not be able to get a valid score.
Is the location address missing in Envizi?
The post code in the Location address is required when calculating the score as it determines the weather factors to be used in the score calculation.
Has the location's region been set up correctly?
The 'Region' of the Location must be set up and be a valid region.
Do you have special character such as '&' in the account name?
Special character such as '&' is not supported by the API and hence can cause the API to fail. Remove or replace the special character and then try again.
Are the property use details missing in Envizi?
Property details such as floor area sq ft and % air-conditioned area should be kept up to date in Envizi to get a valid score.
Is property use details available or up-to-date for the selected rating end month?
Property details such as floor area sq ft and % air-conditioned area should be available for the selected month. The API does not use account accruals in stats, but relying on account records captured.
Have the mappings between the Envizi locations, accounts and meters, and the Portfolio Manager properties and meters been established in Envizi?
The mappings are important especially when you have properties in Portfolio Manager and have granted Envizi access to them. Envizi needs to update the data in ENERGY STAR Portfolio Manager to get a valid score.
Is the ENERGY STAR Portfolio Manager website in maintenance mode?
Go to the ENERGY STAR Portfolio Manager website and check whether any system maintenance is ongoing.
Is weather data available in ENERGY STAR Portfolio Manager?
Weather data in ENERGY STAR Portfolio Manager is typically updated on the 15th of each month for the month before. Requesting a score before the 15th of the month for the month previous might result in an error.
Has Envizi been granted full data access permission for all applicable meters in Portfolio Manager?
If full data access rights are not granted for the property and applicable meters in ENERGY STAR Portfolio Manager, it results in failure of the API job, for both energy and water meters.
Have any negative consumption values been incorrectly entered into water accounts in Envizi?
ENERGY STAR Portfolio Manager does not accept negative consumption values for water accounts. Negative values in water accounts cause API requests to fail. A possible workaround is to add an account consolidation rule to make the water consumption a positive value.
Others
Log in to your ENERGY STAR Portfolio Manager account and check the error, which usually indicates why the score was not calculated.
Special or non-English characters in location address
UTF-8 encoding is supported in API sync requests. Some special or non-English characters in the location address might cause the API to fail to upload property details to ENERGY STAR Portfolio Manager. For example, double spaces, UTF-16 format characters, or other formats except UTF-8. Remove or replace the characters with more commonly used English characters.
Envizi should have been granted full access to all energy and water meters in an ENERGY STAR Portfolio Manager location

If the API failed with a Meter Property association has NOT been set-up properly error message, it is likely due to a permission issue that Envizi does not have full access to all energy and water meters in ENERGY STAR Portfolio Manager, except for IT UPS meters.

It is an ENERGY STAR Portfolio Manager rule that full access to all energy and water meters is required for the Envizi API to edit meters that contribute to metrics. For more information, see the Energy Star permission FAQ article.

If you can confirm that the error is because of a 403 Access Denied code in the API transaction log, login to your Portfolio Manager account and grant Envizi full access to other Energy and Water meters for this location in Portfolio Manager account. It is also important that after you grant Envizi full access, you need to inform Envizi to accept the sharing of meters in Portfolio Manager under the Notifications section before the error can be resolved.

If the previous information does not help to resolve your issue, review the API transaction logs.