Parse an error response

When an API action completes successfully, it returns a status code of ok. If the call is not successful, it can also return any of the following status codes:

invalid Indicates that the call is invalid in some way, usually invalid syntax.

no-access Shows that the current user does not have permission to call the action, and includes a subcode attribute with more information.

no-data Indicates that there is no data available for the action to return, when the action would ordinarily return data.

too-much-data Means that the action should have returned a single result but is actually returning multiple results.

When the status code is invalid, the response also has an invalid element that shows which request parameter is incorrect or missing:

<?xml version="1.0" encoding="utf-8" ?> 
<results>
    <status code="invalid">
        <invalid field="has-children" type="long" subcode="missing" /> 
    </status>
</results>

When the status code is no-access, the subcode explains why:

<?xml version="1.0" encoding="utf-8" ?> 
<results>
    <status code="no-access" subcode="denied" /> 
</results>

All valid values for code, subcode, and invalid are described in status, in the API reference. Your application needs to read and handle status codes and subcodes.

Handle status codes

Write a method that parses an XML API response for the status code and subcode. This is an example in Java:

private String getStatus(Element el) throws JDOMException {
    String code = codePath.valueOf(el);
    String subcode = subcodePath.valueOf(el);
    StringBuffer status = new StringBuffer();
    if(null != code && code.length() > 0)
            status.append(code);
    if(null != subcode && subcode.length() > 0)
            status.append(" - " + subcode);
    return status.toString();
}

When you call an action, parse the response for the status.
If the status is not ok, return a null value, display the error status code for debugging, or throw an application exception.
The action to take depends on which call you are making and how your application is designed.

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/breeze/6/xml_api/02_logi8.htm