Edit

Instrumenting client requests for EWS and REST in Exchange

  • Article

Learn about the HTTP headers in EWS and REST requests and responses that can help you monitor and troubleshoot your Exchange application.

Has this ever happened to you? A user of your application reports an unexpected error. You want to investigate, but you can't reproduce it. The error has disappeared for the user, and you're left with very little actionable data. Frustrating, isn't it? Let's look at how you can proactively prepare for this scenario and hopefully avoid frustration in the future.

Add instrumentation to requests

We recommend that you add additional HTTP headers to your requests to facilitate troubleshooting. You should keep a record of this information somewhere (for example, in a log file) so that you can retrieve it later if you need to. This is helpful when examining network traffic, and is also helpful if you contact Microsoft support for assistance.

Table 1. Request headers for troubleshooting

HTTP header (EWS) EWS Managed API equivalent Notes
User-Agent
ExchangeService.UserAgent
Set this to a unique value that identifies your client application.

Using the same value for all requests that your application sends allows Microsoft to help troubleshoot call failures, should they arise.
client-request-id
ExchangeService.ClientRequestId
Set this to a different unique value for every request your application sends.

We recommend that you use a GUID. This unique identifier is intended to be used to correlate activities between two systems in the event that something goes wrong.
return-client-request-id
ExchangeService.ReturnClientRequestId
Set this to true to signal to the Exchange server that it should return the value of your client-request-id in the corresponding response.

You can use this to correlate requests and responses in network traces or EWS Managed API traces.
X-ClientStatistics
ExchangeService.SendClientLatencies
Used to report EWS latencies to Microsoft if your application is accessing Exchange Online or Exchange Online as part of Office 365.

Log information from responses

Just as your client can add additional instrumentation to the requests it sends, Exchange adds additional instrumentation to the responses in the form of HTTP headers. Your client should capture this information to go along with the request instrumentation information.

Note

If you are using the EWS Managed API, there is no direct equivalent for the HTTP headers. However, all HTTP response headers can be accessed via the ExchangeService.HttpResponseHeaders property.

Table 2. HTTP response headers

HTTP header Description
request-id
A server-generated ID for the request that corresponds to this response.
client-request-id
The value of the client-request-id header in the request.

This header is only present if the request contains the return-client-request-id header with a value of true.
X-FEServer
The FQDN of the Client Access server that processed the request.
X-TargetBEServer
The FQDN of the mailbox server that processed the request.
X-DiagInfo
Additional diagnostic information, depending on the request.
x-ms-diagnostics
This header is only applicable if OAuth authentication is used in the request.

It contains an explicit error code that specifies why an OAuth authentication failed.

It takes the following format: errorId;reason="reason"error_type="error type"

The reason field is a human-readable description of the error.

The errorId field is an integer, and the error_type field is the string representation of that integer, as follows:
  • 2000000: invalid_signature
  • 2000001: invalid_token
  • 2000002: token_expired
  • 2000003: invalid_resource
  • 2000004: invalid_tenant
  • 2000005: invalid_user
  • 2000006: invalid_client
  • 2000007: internal_error
  • 2000008: invalid_grant

Report EWS latency to Microsoft

If your application uses the EWS Managed API or EWS to connect to Exchange Online, you can report latency in EWS requests directly to Microsoft. The information is passed via the X-ClientStatistics request header. If you are using the EWS Managed API, all you have to do is set the ExchangeService.SendClientLatencies property to true. If you are using EWS, you'll need to measure the time between issuing a request and receiving a response, then add the X-ClientStatistics header to the next EWS request your application sends, using the following format.

X-ClientStatistics: MessageId=<value of request-id header>,ResponseTime=<time in milliseconds>,SoapAction=<EWS operation>

We maintain reports for these latencies and use them to continuously improve EWS services in Exchange Online.

Next steps

After you've added client instrumentation to your application, you're better prepared if something goes wrong. If that happens, you can use your instrumentation data to troubleshoot your application.

See also