Table of contents
TOC
Collapse the table of content
Expand the table of content

Errors and informational messages

John Austin|Last Updated: 6/17/2016
|
1 Contributor

Learn about the types of errors and informational messages that are used in UCWA 2.0.

Applies to: Skype for Business 2015

To report failures, UCWA 2.0 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 2.0 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 2.0 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 2.0 by analyzing the Content-Type header. In this release, the supported content types are:

  • application/json

  • application/xml

Error types

UCWA 2.0 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.

ErrorDescription
ApplicationNotFoundThe application resource does not exist.
BadRequestSomething is wrong with the entire request (malformed XML/JSON, for example).
DeserializationFailureThe request body could not be deserialized. Please check if the body confirms to allowed formats and does not have any invalid characters.
EntityTooLargeThe request is too large.
InactiveApplicationExpiredAn inactive application expired.
MethodNotAllowedThe requested HTTP method is not supported for this resource.
MobileApplicationNoLongerAllowedUser is no longer authorized for mobile applications.
ParameterValidationFailureA parameter value is not valid.
PreconditionFailedAn If-Match precondition was not met.
PreconditionRequiredThe operation requires an If-Match precondition.
ResourceNotFoundThe resource does not exist.
ServiceFailureInternal Server Error.
ServiceTimeoutInternal Server Error, remote timeout.
TooManyApplicationsThere are too many applications for this user.
UnsupportedMediaTypeThe content-type is not supported.
VersionNotSupportedRequested 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 nameTypeRequired in error response?Description
codeStringYesFor synchronous failures, this maps one-to-one with HTTP responses. For asynchronous failures or messages, it is contextual.
subcodeStringNoThe subcode further classifies a failure. For example, if the response code is 409 Conflict, the subcode could be 'AlreadyExists'.
messageStringNoThe message provides a reason, localized to the user's locale that was specified when application was created.
linkhrefNoThe link potentially can provide further information about the error and how to resolve the problem.
parametersProperty bagNoParameters 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.
debugInfoProperty bagNoA 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 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 codeErrorCan appear in event channel?
400BadRequestYes
403ForbiddenYes
404NotFoundYes
405MethodNotAllowedNo
408ClientTimeoutNo
409ConflictYes
410GoneNo
412PreConditionFailedNo
413EntityTooLargeYes
415UnsupportedMediaTypeNo
428PreConditionRequiredNo
429TooManyRequestsNo
500ServiceFailureYes
503ServiceUnavailableNo
504TimeoutYes
© 2017 Microsoft