Share via

How to interpret SOAP Faults

  • Article

Apologies for the delay in this post.  I use Windows Live Writer to compose the content on this blog.  It is a wonderful program that makes writing posts easy and straight-forward.  Best of all, it allows offline editing of new and existing posts.  The downside, though, is when you forget to publish the changes!

Before we plough forward into using the sample client from the previous post, we must first discuss the different types of SOAP Faults you may receive.  A SOAP Fault is conceptually similar to a .NET exception in that it represents an error condition.  A SOAP Fault may be returned instead of any response message.  The Fault is itself a SOAP Message with header and body.  The key difference is the body MUST have a fault element.  The fault is officially defined in the SOAP Spec.

There are four main faults we will cover: InvalidRepresentation, EndpointUnavailable, PermissionDenied, and AuthorizationRequired.

InvalidRepresentation

This fault is thrown when either the SOAP request is malformed or the XML representation of the ILM Object does not validate.  Validation means both that the structure is correct and that the values pass the validation rules on AttributeBindings and AttribueTypeDescriptions.

When you encounter this fault, please inspect the format of the request.  Ensure that the attributes you specify are bound to the object and that their values are valid.  I mostly see this error when I fail to include a required attribute or a set an attribute value to an invalid value.

EndpointUnavailable

This fault is thrown when a catastrophic failure occurs.  It implies a cross-cutting failure from which you cannot recover.

I encourage you to turn on diagnostic tracing and retry the request to see the real failure.  I have never seen this error outside of controlled test cases.

PermissionDenied

This fault is thrown when you do not have permission to read or write to an attribute.  We also throw this fault in the case of non-existent attributes so a malicious user cannot discern what data may exist.

When you encounter this fault, please ensure that the account under which your code is running in fact has the necessary permission.  Three attributes in particular you can never modify even though they are required: ObjectID, CreateTime, and ObjectType.

AuthorizationRequired

Recall the ILM “2” request pipeline: AuthN –> AuthZ –> Effects –> Action.  If a request has an authorization workflow that requires more information then you will get back an AuthZ fault.  If the AuthZ workflow fails you will get back PermissionDenied.  This fault contains the reference to the endpoint of the workflow to complete.  In most cases this is an approval activity which the approver must create an ApprovalResponse object to satisfy.

When you encounter this fault, you must complete the AuthZ workflow.  It is not necessary to resubmit the request as it will be processed once permitted to do so.  Completing the AuthZ workflow is beyond the scope of this topic, and it will be covered in the next series of topics.

Next post we’ll cover a Hello World application using the sample client.

Comments