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 '' 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):


This will return the following response:

  "Id": "3c7f0e3a-623b-85ae-4032-07d41531beff@7aeb6117-c342-4861-bec7-f8803ae85e41",
  "EmailAddress": "",
  "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.


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


Comments are closed. Login to edit/delete your existing comments

Feedback usabilla icon