2.6 Common SOAP Fault Detail

Article
04/06/2021

This section defines a SOAP fault Detail element [SOAP1.2-1/2003] that is used by the ADWS protocol set. This element is used for the "[Detail]" property of [WSASB]. The SOAP fault detail is specified via the following XML schema [XMLSCHEMA1] definition.

 <xsd:schema
     targetNamespace="http://schemas.microsoft.com/2008/1/ActiveDirectory"
     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
     xmlns:ad="http://schemas.microsoft.com/2008/1/ActiveDirectory"
     xmlns:da="http://schemas.microsoft.com/2006/11/IdentityManagement/DirectoryAccess"
     elementFormDefault="qualified">
   <xsd:complexType name="ArgumentErrorType">
     <xsd:sequence>
       <xsd:element name="Message" type="xsd:string" minOccurs="0"/>
       <xsd:element name="ParameterName" type="xsd:string"
                    minOccurs="0"/>
       <xsd:element name="ShortMessage" type="xsd:string"
                    minOccurs="0"/>
     </xsd:sequence>
   </xsd:complexType>
  
   <xsd:complexType name="DirectoryErrorType">
     <xsd:sequence>
       <xsd:element name="Message" type="xsd:string" minOccurs="0"/>
       <xsd:element name="ErrorCode" type="xsd:string" minOccurs="0"/>
       <xsd:element name="ExtendedErrorMessage" type="xsd:string"
                    minOccurs="0"/>
       <xsd:element name="MatchedDN" type="xsd:string" minOccurs="0"/>
       <xsd:element name="Referral" type="xsd:string" minOccurs="0"
                    maxOccurs="unbounded"/>
       <xsd:element name="Win32ErrorCode" type="xsd:string" minOccurs="0"/>
       <xsd:element name="ShortMessage" type="xsd:string" minOccurs="0"/>
     </xsd:sequence>
   </xsd:complexType>
  
   <xsd:complexType name="ChangeType">
     <xsd:sequence>
       <xsd:element name="AttributeType" type="da:AttributeType"/>
       <xsd:element name="AttributeValue" type="da:AttributeValue"/>
     </xsd:sequence>
     <xsd:attribute name="Operation" type="xsd:string"/>
   </xsd:complexType>
  
   <xsd:complexType name="InvalidAttributeTypeOrValueType">
     <xsd:sequence>
       <xsd:element name="AttributeType" type="da:AttributeType"/>
       <xsd:element name="AttributeValue" type="da:AttributeValue"/>
     </xsd:sequence>
   </xsd:complexType>
  
   <xsd:complexType name="FaultDetailType">
     <xsd:sequence>
       <xsd:element name="Error" type="xsd:string" minOccurs="0"/>
       <xsd:choice>
         <xsd:element name="ArgumentError" type="ad:ArgumentErrorType"/>
         <xsd:element name="DirectoryError" type="ad:DirectoryErrorType"/>
         <xsd:element name="InvalidAttributeType" type="xsd:string"/>
         <xsd:element name="InvalidOperation" type="xsd:string"/>
         <xsd:element name="InvalidChange" type="ad:ChangeType"/>
         <xsd:element name="InvalidAttributeTypeOrValue"
                      type="ad:InvalidAttributeTypeOrValueType"/>
       </xsd:choice>
       <xsd:element name="ShortError" type="xsd:string" minOccurs="0"/>
     </xsd:sequence>
   </xsd:complexType>
  
   <xsd:element name="FaultDetail" type="ad:FaultDetailType"/>
  
 </xsd:schema>

In the following descriptions, XPath 1.0 [XPATH] notation is used to indicate the XML element or attribute that is being referred to.

A single SOAP fault can specify ad:FaultDetail/ad:Error, ad:FaultDetail/ad:ShortError, or both in addition to exactly one of the following:<6>

ad:FaultDetail/ad:ArgumentError
ad:FaultDetail/ad:DirectoryError
ad:FaultDetail/ad:InvalidAttributeType
ad:FaultDetail/ad:InvalidOperation
ad:FaultDetail/ad:InvalidChange
ad:FaultDetail/ad:InvalidAttributeTypeOrValue

The use of ad:FaultDetail/ad:ArgumentError is implementation-defined.<7>

The presence of ad:FaultDetail/ad:DirectoryError in a SOAP fault indicates that an error was returned by the directory service.

Element	Contents
ad:FaultDetail/ad:DirectoryError/ad:Message	A human-readable error message string explaining the nature of the directory error that occurred.
ad:FaultDetail/ad:DirectoryError/ad:ErrorCode	An LDAP resultCode as specified in [RFC2251].
ad:FaultDetail/ad:DirectoryError/ad:ExtendedErrorMessage	An LDAP errorMessage as specified in [RFC2251].
ad:FaultDetail/ad:DirectoryError/ad:MatchedDN	An LDAP matchedDN as specified in [RFC2251].
ad:FaultDetail/ad:DirectoryError/ad:Referral	An LDAP referral URL as specified in [RFC2251].
ad:FaultDetail/ad:DirectoryError/ad:Win32ErrorCode	An error code generated from ad:ErrorCode(*).
ad:FaultDetail/ad:DirectoryError/ad:ShortMessage	A non-localized error message string representing the nature of the directory error that occurred in ad:Message(**).

(*) The information in the following product behavior note applies to this element.<8>

(**) The information in the following product behavior note applies to this element.<9>

The ad:FaultDetail/ad:InvalidAttributeType element indicates that a [MS-WSTIM] ModifyRequest operation specified a da:ModifyRequest/da:Change/da:AttributeValue when a value was not permitted to be specified by the setting of the da:ModifyRequest/da:Change/@Operation attribute, or did not specify a value when one was required by the setting of that attribute.

Element	Contents
ad:FaultDetail/ad:InvalidAttributeType	The value of the da:ModifyRequest/da:Change/da:AttributeType for the da:ModifyRequest/da:Change with the incorrectly specified value.

The ad:FaultDetail/ad:InvalidOperation element indicates that a [MS-WSTIM] ModifyRequest operation specified an invalid value for the da:ModifyRequest/da:Change/@Operation attribute.

Element	Contents
ad:FaultDetail/ad:InvalidOperation	The invalid value specified for the da:ModifyRequest/da:Change/@Operation attribute.

The ad:FaultDetail/ad:InvalidChange element indicates that a [MS-WSTIM] ModifyRequest specified an invalid value for the contents of a da:ModifyRequest/da:Change/da:AttributeValue.

Element	Contents
ad:FaultDetail/ad:InvalidChange/@Operation	The value of the da:ModifyRequest/da:Change/@Operation attribute for the da:ModifyRequest/da:Change with the invalid value.
ad:FaultDetail/ad:InvalidChange/da:AttributeType	The value of the da:ModifyRequest/da:Change/da:AttributeType for the da:ModifyRequest/da:Change with the invalid value.
ad:FaultDetail/ad:InvalidChange/da:AttributeValue	The value of the da:ModifyRequest/da:Change/da:AttributeValue for the da:ModifyRequest/da:Change with the invalid value.

The ad:FaultDetail/ad:InvalidAttributeTypeOrValue element indicates that a [MS-WSTIM] AddRequest specified an invalid da:AddRequest/da:AttributeTypeAndValue.

Element	Contents
ad:FaultDetail/ad:InvalidAttributeTypeOrValue/da:AttributeType	The value of the da:AddRequest/da:AttributeTypeAndValue/da:AttributeType for the invalid da:AddRequest/da:AttributeTypeAndValue.
ad:FaultDetail/ad:InvalidAttributeTypeOrValue/da:AttributeValue	The value of the da:AddRequest/da:AttributeTypeAndValue/da:AttributeValue for the invalid da:AddRequest/da:AttributeTypeAndValue.

The ad:FaultDetail/ad:Error element provides a human-readable error explaining the error. This option is used when none of the other options apply and can be used in addition to the other options. Unlike ad:FaultDetail/ad:DirectoryError/ad:Message, the contents of ad:FaultDetail/ad:Error/ad:Message need not be an error related to the directory service.

Element	Contents
ad:FaultDetail/ad:Error	A human-readable error message string explaining the nature of the error that occurred.

For example, the following demonstrates the SOAP fault detail that could be returned when the directory service returns an LDAP referral error code.

  
  
 <soapenv:Envelope>
   <soapenv:Header>
   ....
   </soapenv:Header>
   <soapenv:Body>
     <soapenv:Fault>
       ....
       <soapenv:Detail>
         <FaultDetail
             xmlns="http://schemas.microsoft.com/2008/1/ActiveDirectory">
           <DirectoryError>
             <Message>An operation error occurred.</Message>
             <ErrorCode>10</ErrorCode>
             <ExtendedErrorMessage>
               0000202B: RefErr: DSID-03100768, data 0, 1 access points ref 1: 'server01.fabrikam.com'
             </ExtendedErrorMessage>
             <MatchedDN>
             </MatchedDN>
             <Referral>
               ldap://server01.fabrikam.com/CN=Test,DC=fabrikam,DC=com
             </Referral>
             <ShortMessage>ELdap</ShortMessage>
             <Win32ErrorCode>8235</Win32ErrorCode>
           </DirectoryError>
         </FaultDetail>
       </soapenv:Detail>
     </soapenv:Fault>
   </soapenv:Body>
 </soapenv:Envelope>

2.6 Common SOAP Fault Detail

Additional resources