Errors

  • Article

This section outlines error that may be issues by Windows Web Services functions in result of a failure to execute the command.

Out Parameters

As a general rule, the value of out parameters are not modified if a function fails.

There are a few instances where out parameters are modified if the function fails. These cases are explicitly called out in the documentation for each parameter. If the documentation does not mention anything about modifying out parameters in the case of failure, then you can safely assume that the function will not modify them.

Error Codes

All error return codes are HRESULTs. This API defines a set of HRESULTs in the FACILITY_WEBSERVICES range, but also returns errors defined elsewhere in the Windows API.

Refer to the documentation for specific API's to learn about which error codes are returned. The list is not intended to be exhaustive for each API, but rather a list of error codes for which there are common scenarios for explicit handling. A caller should always assume other error codes are possible from any API.

This API defines a relatively small number of error codes, which correspond to scenarios where a program will want to take action based on the error. Error codes alone may not be sufficient in order to determine what went wrong, or in order to provide a good description of the problem to the user. The best understanding of the problem comes from using Rich Errors, as described below.

Rich Errors

In additional to returning an error code, a caller may optionally request rich error information for any API call by passing a non-NULLWS_ERROR object. To create an error object, use WsCreateError. If there is an error, then the API that caused the error will fill the error object with additional context about the error situation. If there is no error, then the error object is unmodified. Passing a NULL error object indicates that the caller is not interested in rich error information. Callees (including callbacks) must be prepared to handle NULL error objects.

Note that the same error object can be used for multiple API calls, but may only be used for one API call at a time (as it is single threaded). Each time an error occurs, error information is appended to the error object. As a call chain unwinds, multiple functions may add information to the error object to provide additional context about the error. To clear the contents of the error object before reusing it (after an error occurs), use WsResetError. If no error occurs, it is not necessary to reset the error object before reusing it.

Rich error information consists of the following:

Faults and Errors

See Faults for information about how errors and faults relate.

Language Sensitive Error Information

When creating an error object, the LANGID of the desired language translation for error information is specified. This is used when adding error information to the error object.

This language value can be retrieved or set using WS_ERROR_PROPERTY_LANGID.

Canonical Error Codes

This API provides a canonical set of error codes (WS_E_*) that allow for different communication technologies to be used without having to depend on the specific error codes of the specific underlying implementation. For a complete list of these error codes, see Windows Web Services Return Values.

This allows, for example, a program to check for the error code WS_E_ENDPOINT_NOT_FOUND whether using TCP, UDP, or HTTP, and take some action (like attempting to use a different endpoint).

When an implementation specific error code is mapped to a canonical error, the original error code is saved in the error object, and may still be accessed for diagnostic purposes. See WS_ERROR_PROPERTY_ORIGINAL_ERROR_CODE for more information.

Invalid API Usage

The following error codes are reserved for invalid API usage, and will not be returned in other circumstances. If any of these errors are returned it may be an indication of an application bug.

  • WS_E_INVALID_OPERATION
  • E_INVALIDARG

The following enumerations are part of tracing:

The following error codes are part of tracing:

  • CERT_E_CN_NO_MATCH
  • CERT_E_EXPIRED
  • CERT_E_UNTRUSTEDROOT
  • CERT_E_WRONG_USAGE
  • CRYPT_E_REVOCATION_OFFLINE
  • E_INVALIDARG
  • E_OUTOFMEMORY
  • WS_E_ADDRESS_IN_USE
  • WS_E_ADDRESS_NOT_AVAILABLE
  • WS_E_ENDPOINT_ACCESS_DENIED
  • WS_E_ENDPOINT_ACTION_NOT_SUPPORTED
  • WS_E_ENDPOINT_DISCONNECTED
  • WS_E_ENDPOINT_FAILURE
  • WS_E_ENDPOINT_FAULT_RECEIVED
  • WS_E_ENDPOINT_NOT_AVAILABLE
  • WS_E_ENDPOINT_NOT_FOUND
  • WS_E_ENDPOINT_TOO_BUSY
  • WS_E_ENDPOINT_UNREACHABLE
  • WS_E_INVALID_ENDPOINT_URL
  • WS_E_INVALID_FORMAT
  • WS_E_INVALID_OPERATION
  • WS_E_NOT_SUPPORTED
  • WS_E_NO_TRANSLATION_AVAILABLE
  • WS_E_NUMERIC_OVERFLOW
  • WS_E_OBJECT_FAULTED
  • WS_E_OPERATION_ABANDONED
  • WS_E_OPERATION_ABORTED
  • WS_E_OPERATION_TIMED_OUT
  • WS_E_OTHER
  • WS_E_PROXY_ACCESS_DENIED
  • WS_E_PROXY_FAILURE
  • WS_E_PROXY_REQUIRES_BASIC_AUTH
  • WS_E_PROXY_REQUIRES_DIGEST_AUTH
  • WS_E_PROXY_REQUIRES_NEGOTIATE_AUTH
  • WS_E_PROXY_REQUIRES_NTLM_AUTH
  • WS_E_QUOTA_EXCEEDED
  • WS_E_SECURITY_SYSTEM_FAILURE
  • WS_E_SECURITY_TOKEN_EXPIRED
  • WS_E_SECURITY_VERIFICATION_FAILURE
  • WS_E_SERVER_REQUIRES_BASIC_AUTH
  • WS_E_SERVER_REQUIRES_DIGEST_AUTH
  • WS_E_SERVER_REQUIRES_NEGOTIATE_AUTH
  • WS_E_SERVER_REQUIRES_NTLM_AUTH
  • WS_S_ASYNC
  • WS_S_END

The following functions are part of tracing:

The following handle is part of tracing:

The following structure is part of tracing:

Security

There are a number of security considerations that the user of the error object should be aware of:

  • The error object may contain untrusted data. Examples of this are: the WS_FAULT, and the error strings, both of which can be stored in the error object based on information received over an untrusted channel. The user of the error object should be careful when inspecting the information in the error object and making decisions based on its values.
  • A user of the error object should call WsResetError after inspecting the information about the error. Failing to do so can lead to memory accumulation.
  • A user of the error object should be very careful when using the WS_FULL_FAULT_DISCLOSURE value of the WS_FAULT_DISCLOSURE enumeration, because the generated fault could contain private information that was accumulated as part of the error recording process.