|
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.
|
|
|
