Exception Handling in the SoftLayer API

From SoftLayer Development Network Wiki

Like any programming interface the SoftLayer API at times needs to return error messages to its users. The SoftLayer API brings these exceptions forward to the user so their application can handle the unexpected result. Exceptions are returned as SOAP or XML-RPC faults depending on the RPC method used to execute your API method call. Programming and scripting languages with SOAP and XML-RPC support usually have built-in methods for handling faults, but if you are manually processing your API response a SOAP Fault is akin to this:

 
<SOAP-ENV:Fault>
    <faultcode>MY_FAULT_CODE</faultcode>
    <faultstring>MY_EXCEPTION</faultstring>
</SOAP-ENV:Fault>

while its XML-RPC counterpart resembles this:

 
<?xml version="1.0"?>
<methodResponse>
    <fault>
        <value>
            <struct>
                <member>
                    <name>faultCode</name>
                    <value>
                        <int>1</int>
                     </value>
                 </member>
                 <member>
                     <name>faultString</name>
                     <value>
                         <string>MY_EXCEPTION</string>
                     </value>
                 </member>
             </struct>
         </value>
     </fault>
</methodResponse>

Method calls are halted if exceptions are encountered during their execution. The specialized exceptions that a method can throw are listed on that method's manual page.

Common Exceptions

Though the exceptions that each method can throw are listed on that method's manual page, the SoftLayer API throws a number of more common exceptions in the case of a general failure. These exceptions include:

"No valid authentication headers found" if an authenticate header was not passed to your method call.
"Invalid API token." if the username or API key passed to your method are incorrect.
"SOAP-ERROR: Encoding: Violation of encoding rules" if a SOAP API call is passing an incorrect data type in its request (for instance, a string where an integer is expected).