Errors and Informational Messages

Errors and Informational Messages

To report failures, UCWA uses the failure response classes (4xx & 5xx) that are defined in Section 10 (Status Code Definitions) of the HTTP RFC. An HTTP request that is targeted to UCWA can have multiple intermediate proxies on the path, meaning an intermediate component can return a failure response of 4xx or 5xx as well.

If UCWA responds with a failure, it will provide supplementary information in the error response that can be used to aid in problem diagnosis or drive the user interface. Clients can determine whether the response comes from UCWA by analyzing the Content-Type header. In this release, the supported content types are:

  • application/json
  • application/xml

Error types

UCWA categorizes errors as either synchronous or asynchronous based on their presence in the command or event channels, respectively.

Synchronous Errors

Synchronous errors are returned only in the command channel in response to GET, POST, PUT, or DELETE requests. These errors map one-to-one to the familiar HTTP response codes.

The errors listed in the following table apply to most resources.

Error Description
ApplicationNotFound The application resource does not exist.
BadRequest Something is wrong with the entire request (malformed XML/JSON, for example).
DeserializationFailure The request body could not be deserialized. Please check if the body confirms to allowed formats and does not have any invalid characters.
EntityTooLarge The request is too large.
InactiveApplicationExpired An inactive application expired.
MethodNotAllowed The requested HTTP method is not supported for this resource.
MobileApplicationNoLongerAllowed User is no longer authorized for mobile applications.
ParameterValidationFailure A parameter value is not valid.
PreconditionFailed An If-Match precondition was not met.
PreconditionRequired The operation requires an If-Match precondition.
ResourceNotFound The resource does not exist.
ServiceFailure Internal Server Error.
ServiceTimeout Internal Server Error, remote timeout.
TooManyApplications There are too many applications for this user.
UnsupportedMediaType The content-type is not supported.
VersionNotSupported Requested Version is not supported.

Asynchronous Errors

Asynchronous errors are returned only in the event channel, and are used to indicate failure reasons. These errors are associated exclusively with operation resources such as the onlineMeetingInvitation resource.

Asynchronous Informational Messages

Asynchronous informational messages are also returned only in the event channel, but are used to provide additional information on why a dynamic resource was updated (that is, the reason for a state transition).

Error Response Body

The following table lists the properties in an error response body.

Property name Type Required in error response? Description
code String Yes For synchronous failures, this maps one-to-one with HTTP responses. For asynchronous failures or messages, it is contextual.
subcode String No The subcode further classifies a failure. For example, if the response code is 409 Conflict, the subcode could be 'AlreadyExists'.
message String No The message provides a reason, localized to the user's locale that was specified when application was created.
link href No The link potentially can provide further information about the error and how to resolve the problem.
parameters Property bag No Parameters apply only for response codes of 400 Bad Request. In this case a property bag will list all of the invalid properties in the request that the response refers to.
debugInfo Property bag No A property bag that provides supplementary information that can be used for troubleshooting.

Client/Server Programming Contract

  • The only property that is required in the error body is "code". All other properties are optional.
  • New subcodes can be introduced at any time. Clients should be designed that that they ignore missing or unknown subcodes.
  • Both Code and Subcode should be consumed contextually. For example, if the messaging modality sends an updated event, with a subcode of "Removed", this means that the messaging modality was removed. There are no modality-specific subcodes.

Anything that resides under <debugInfo> is subject to change, so a client must not make assumptions about the contents of this property. However, clients are recommended to log this information along with the failed request. These items can provide substantial help when troubleshooting the problem.

Error Sample - JSON

The following shows the form of a 400 BadRequest error body in JSON format.

{
  "code": "Conflict",
  "subcode": "AlreadyExists",
  "message": "The requested resource already exists. Please wait and try again."
}

Error Sample - XML

The following shows the general form of a 409 Conflict error body in XML format.

<?xml version="1.0" encoding="utf-8"?>
<reason xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.microsoft.com/rtc/2012/03/ucwa">
  <code>Conflict</code>
  <subcode>AlreadyExists</subcode>
  <message>The requested resource already exists. Please wait and try again.</message>
  <debugInfo />
  <parameters />
</reason>

HTTP Error Codes Returned by UCWA

HTTP status code Error Can appear in event channel?
400 BadRequest Yes
403 Forbidden Yes
404 NotFound Yes
405 MethodNotAllowed No
408 ClientTimeout No
409 Conflict Yes
410 Gone No
412 PreConditionFailed No
413 EntityTooLarge Yes
415 UnsupportedMediaType No
428 PreConditionRequired No
429 TooManyRequests No
500 ServiceFailure Yes
503 ServiceUnavailable No
504 Timeout Yes