Error improvement for invalid X-AnchorMailbox in REST API calls

Jason Johnston

Update 1/29: Based on feedback, we’ve adjusted the HTTP status code to 400 instead of 421. All other details remain the same.

We wanted to give you a heads-up on a recent change to the error returned by the Outlook REST API when the value of the X-AnchorMailbox is incorrect. If your app has error-handling for this scenario based on the current behavior of the service, this may be a breaking change.

Starting immediately, the service will start returning a 400 Bad Request status instead of a 503 Service Unavailable. The intent of this change is to return a more appropriate HTTP status and to make it easier for developers to detect why the request failed and fix the problem.

Old behavior

Prior to this change, sending a REST API request with an incorrect X-AnchorMailbox header would result in the following response.

HTTP/1.1 503 Service Unavailable

{
  "error": {
    "code": "MailboxInfoStale",
    "message": "Mailbox info is stale."
  }
}

New behavior

With this change, if your app receives a 400 HTTP status from a REST call, you should check the response body for an error object, then check the code property. If it is ErrorIncorrectRoutingHint, the value you sent in the X-AnchorMailbox is incorrect.

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "ErrorIncorrectRoutingHint",
    "message": "The x-anchor mailbox 'jason@contoso.com' does not match the target of the request."
  }
}

Handling the error

If your app gets this error, it is recommended that you get the user’s mailbox GUID and use that for the X-AnchorMailbox value, instead of the user’s SMTP address. You can get the user’s mailbox GUID by making the following REST request (with no X-AnchorMailboxheader):

GET https://outlook.office.com/api/v2.0/me

This will return the following response:

{
  "Id": "3c7f0e3a-623b-85ae-4032-07d41531beff@7aeb6117-c342-4861-bec7-f8803ae85e41",
  "EmailAddress": "jason@contoso.onmicrosoft.com",
  "DisplayName": "Jason Johnston",
  "Alias": "jason",
  "MailboxGuid": "fece2b65-3577-4972-bf3d-5594fc9c9f9e"
}

You would then use the value of MailboxGuid in the X-AnchorMailbox for subsequent REST calls.

GET https://outlook.office.com/api/v2.0/me/messages

X-AnchorMailbox: fece2b65-3577-4972-bf3d-5594fc9c9f9e

Jason Johnston

Follow