Errors and status returned by the Office 365 Reporting web service

  • Article

In addition to standard HTTP response codes, the Office 365 Reporting web service returns errors if problems occur while processing the request. This topic describes those errors, provides suggestions for avoiding them where possible, and helps developers troubleshoot their Reporting web service applications.

Applies to: Office 365

In this article
Where errors are indicated
Preventing problems
Simple mistakes
Normal conditions that seem like problems
Uncontrollable events

Where errors are indicated

There are four primary locations where you'll receive errors:

HTTP response codes

Like any HTTP-based web service, the Reporting web service can return HTTP response codes. The standard location for their definition is http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html. In particular, watch out for these errors:

  • HTTP 400 Bad Request: this is returned when the query has syntax issues, or you've given conflicting request information. You'll also get an error payload in the Atom or JSON response with more details.

  • HTTP 403: Forbidden: you'll get this when the credentials you pass are either wrong, or the account has insufficient administrative privileges, or you're requesting a report that you don't have privileges to access.

  • HTTP 404: Not found: is very common during development, if you have the report name wrong.

<ServiceFault> XML document and JSON Error object

Most errors you'll see during development come from malformed requests, bad column names, and so on. When you receive them, read them carefully, as they often tell you exactly where the problem is. The following is an example of what an error returned in JSON format. This first one is the result of typing a column name incorrectly.

  {
    "error":
      {
        "code":"",
        "message":
          {
            "lang":"en-US",
            "value":"Type 'TenantReporting.MailFilterListReport' does not have a property named 'Organizations'; 
            there is no service action named 'Organizations' that is bindable to the type 
           'TenantReporting.MailFilterListReport'; and there is no type with the name 'Organizations'."
          } 
      }
  }

This error was returned in Atom format when the syntax of a $filter option was wrong, in this case the date-time string is in the wrong format.

<?xml version="1.0" encoding="utf-8"?>
<m:error xmlns:m="https://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
  <m:code />
  <m:message xml:lang="en-US">Unrecognized 'Edm.DateTime' literal 'datetime'2013010T00:00:00'' in '86'.</m:message>
</m:error>

Your application also should be aware it might receive report-specific errors and handle them appropriately. Thankfully, once you have the URI-construction logic debugged, those errors will be rare.

Empty report results

Sometimes, report results that are empty are fully correct. Other times, small errors like misspelling a user name, getting the case wrong on a Transport rule, and other minor problems will seem to work fine, but produce no results. One frustrating error of that nature is trying to call the MailDetail report: it always returns no data, so don't bother trying.

Exceptions raised in code

Definitely always catch exceptions in your code. However, often those errors are normal responses to normal errors in the HTTP protocol handling and not always related to the Reporting web service.

Preventing problems

The following list describes best practices that can help prevent difficult troubleshooting tasks during development and use:

  • Don't cache the service document or the MailFilterList results for too long. You don't need to get them every ten minutes, but in a large organization with multiple or many administrators, changes in the names policies and rules do occur, and your system needs to handle those infrequent changes gracefully.

  • Ensure that the service is available before you make the report request. Don't assume the service is functioning. Check it by periodically requesting the service document, and verify that the report you intend to call is present. You do not need to do this every request, but definitely when your application starts.

  • Always use the MailFilterList output for names. The names of things such as Data Leakage Prevention policy and rule names are frequently typed into a form by a human administrator, and spelling errors do occur. By relying on the MailFilterList results, you ensure that the names you pass to the Reporting web service are accurate.

  • Use and verify $metadata. The $metadata document includes all the field names for each report. Consider having the application retrieve, verify and use those names from startup. Alternatively, you should carefully verify that the column names your application uses are the same as those in the $metadata document.

  • Include a service version in your request, and check that the response has the same one. Be careful, however, that you only specify that service version once. Your application can specify it in either an HTTP header, or as a parameter in the REST URI. If you supply both, the Reporting web service returns an error, even when you specify the same service version in both places.

  • Don't allow redirects in the HttpWebRequest. Set AllowAutoRedirect to false.

  • Verify that the HTTP Content-Length response header matches the length of the response buffer before passing the data to an XML parser, and before processing the JSON data in the browser. If you pass a partial response in either you can cause issues both major and subtle.

  • Explicitly set the Accept-Language HTTP request header. Currently there is nothing localized that comes through the Reporting web service, but that can change, and if your customers are using a different culture setting, your application might display information incorrectly.

  • Return any server cookies sent to your application in the next request.

  • Ignore "edit" links some reports return <link rel="edit" title="" ... /> entries in Atom-formatted results. The report data is always read-only, and your application should not attempt to use the links to modify the data.

  • Don't store user names and passwords as text constants in your application, and if you must request them from your user, store them securely in a .NET FrameworkSecureString.

  • Provide a logging facility. When your application experiences runtime, networking, and web service errors, it should have the ability to log everything about the request and response. This will help you troubleshoot, and might be needed if Microsoft customer support has to troubleshoot the issue within Office 365.

  • Don't call the MailDetails report, as it always returns an empty report.

Simple mistakes

The following are some issues we experienced while writing and developing the sample application. They were all common occurrences until we became familiar with making report requests:

  • Carefully check the column naming against the documentation.

  • Carefully check the report naming. HTTP 404 errors are returned when the report name is wrong. The best way to prevent this is to only use the report names that come from the Reporting.svc service description document.

  • Use only names from the MailFilterList report when matching items that it covers. Message processing events, policy, and rule names should all be obtained from only that document to ensure proper spelling and that the value actually exists.

  • If you use StartDate, you must include EndDate. They are both marked as optional, but if you include one you must also include the other.

  • When using StartDate, EndDate or Date, use the correct syntax The ODATA syntax for specifying date-time values is quite a bit more restrictive than other standards. The ODATA Primitive Data Types specification provides details.

  • Remember datetime and guid type casts in $filter options. You will receive data type incompatible errors if you don't cast the string datetime and guid values you're filtering with.

  • Not all reports use StartDate and EndDate. For more information, see How to: Specify reporting time spans.

  • Don't request the service version twice.

  • ODATA allows only one of each query option. Don't include two $filter options, for example.

Normal conditions that seem like problems

The following conditions sometimes seem to developers and users to be problems, but might be normal for the Reporting web service:

  • Data is not available immediately. Most types of information about mail processing, message tracing, and so on are available to the reports within a couple of hours. However, none of the data will appear "instantly." Creating user accounts and mailbox changes very often won't be available until the next calendar day, so that can mean as much as 48 hours delay. Your application should take that into consideration and appropriately set user expectations.

  • Empty report results are sometimes normal, or occur due to restrictive time spans or strict matching criteria. If this is normal for your application, you should provide some way for the user to know that the report request succeeded but there was no data.

  • Reports can take more than a couple of seconds depending on the amount of detail data. Your application should time how long the reports take to retrieve, provide status, and set user expectations accordingly. You might also receive retry-able data mart timeout errors.

  • 2000 is the maximum number of rows that any report can return.

  • The $top and $orderby options are not supported by all reports; check the reference documentation for the report you're using to learn whether it supports those query options. Some reports ignore those options and don't indicate any error.

  • Report data is eventually deleted. Most data is kept for one year, and message trace data is only kept for 40 days. Detailed message trace data is only available for 48 hours from the final message disposition. Keep that in mind as you set reporting time spans and try to trace message delivery issues.

  • Lync users must be logged into their organization account. Organization users can attend Lync conferences as "Guest" or logged into their user account. Conference resources listed in the reports only accumulate minutes for participants who are attending logged into their organization account. In addition, no minutes accumulate for participants attending on a mobile device. Yes, you read that right: if they're attending via mobile, they won't show up (yet).

  • Lync participation via mobile devices are not included. None of the Lync reports include sessions or time used by participants on mobile devices.

  • Lync reports only include self-organized conferences The Lync reports return time and sessions counts for only conferences that were organized by a user of the organization. Because different Lync Online plans might not include the ability to organize conferences, but may still have the ability to participate in them, the number of conferences organized within that tenant could feasibly always return zero.

  • MxRecordReport, OutboundConnectorReport and ServiceDeliveryReport report only current conditions These three reports return information about the current configuration and condition of the Office 365 systems. They do not return historical or summary information.

Uncontrollable events

The Office 365 Reporting web service is an integrated service, receiving data from a wide variety of sources and datacenters. The following list describes some of the things your application might encounter that it has little or no control over:

  • The Reporting web service depends on the Exchange Online infrastructure. For that reason, if the Exchange Online service is unavailable because of planned or unplanned downtime, the Reporting web service might also be unavailable.

  • Exchange Server throttling policies may affect response times. If your application makes a lot of requests, or your dashboard website uses a single service account to gather all the reporting data, you might encounter throttling of your requests. In Office 365, your organization's administrators have no control over the throttling settings, nor can they even read what the current settings are. Be careful about how much Office 365 resources you assume are available.

  • Delayed or lost connection to the datamart. Sometimes when the reporting databases are under heavy load, or are being updated with a lot of new information, the Reporting web service can become temporarily unavailable, or time-out. The ConnectionFailedException error you receive will be "Failed to connect to the datamart." or similar. This is almost never a problem with your application, but you should retry the request, and eventually inform your users that the data or service might be unavailable.