- Preface
- Cisco XML API Overview
- Cisco XML Router Configuration and Management
- Cisco XML Operational Requests and Fault Management
- Cisco XML and Native Data Operations
- Cisco XML and Native Data Access Techniques
- Cisco XML and Encapsulated CLI Operations
- Cisco XML and Large Data Retrieval
- Cisco XML Security
- Cisco XML Schema Versioning
- Alarms
- Error Reporting in Cisco XML Responses
- Summary of Cisco XML API Configuration Tags
- Cisco XML Transport and Event Notifications
- Cisco XML Schemas
- Network Configuration Protocol
- Cisco IOS XR Perl Scripting Toolkit
- Sample BGP Configuration
- Glossary
- Index
Error Reporting in Cisco XML Responses
The XML responses returned by the router contains error information as appropriate, including the operation, object, and cause of the error when possible. The error codes and messages returned from the router may originate in the XML agent or in one of the other infrastructure layers; for example, the XML Service Library, XML Parser Library, or Configuration Manager.
Types of Reported Errors
The types of potential errors in XML Responses are listed in Table 11-1.
These error categories are described in the following sections:
Error Attributes
If one or more errors occur during the processing of a requested operation, the corresponding XML response includes error information for each element or object class in error. The error information is included in the form of ErrorCode and ErrorMsg attributes providing a relevant error code and error message respectively.
If one or more errors occur during the processing of an operation, error information is included for each error at the appropriate point in the response. In addition, error attributes are added at the operation element level. As a result, the client application does not have to search through the entire response to determine if an error has occurred. However, the client can still search through the response to identify each of the specific error conditions.
Transport Errors
Transport-specific errors, including failed authentication attempts, are handled by the appropriate XML agent.
XML Parse Errors
This general category of errors includes those resulting from malformed XML and mismatched XML tags.
The router checks each XML request, but does not validate the request against an XML schema. If the XML contains invalid syntax and thus fails the well-formedness check, the error indication is returned in the form of error attributes placed at the appropriate point in the response. In such cases, the response may not contain the same XML as was received in the request, but just the portions to the point where the syntax error was encountered.
In the following example, the client application sends a request to the router that contains mismatched tags, that is, the opening <BGPEntity> tag is not paired with a closing </BGPEntity> tag. This example illustrates the format and placement of the error attributes.
Note 
The actual error codes and messages might be different than what is shown in this example. Also, the actual error attributes does not contain new line characters.
Sample XML Client Request Containing Mismatched Tags
<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
<Get>
<Configuration>
<BGP MajorVersion="24" MinorVersion="0">
<AS>
<Naming>
<AS>0</AS>
</Naming>
<FourByteAS>
<Naming><AS>3</AS></Naming>
<DefaultVRF>
<BGPEntity>
</DefaultVRF>
</FourByteAS>
</AS>
</BGP>
</Configuration>
</Set>
</Request>
Sample XML Response from the Router
<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0">
<Get xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ErrorCode="0x43679000"
ErrorMsg="'XML Service Library' detected the 'warning'
condition 'An error was encountered in the XML beneath this operation tag
'">
<Configuration ErrorCode="0xa240da00" ErrorMsg="'XML Infrastructure '
detected the 'fatal' condition 'Opening and ending tag does not
match'"/>
</Get>
<ResultSummary ErrorCount="1"/>
</Response>
XML Schema Errors
XML schema errors are detected by the XML operation providers. This general category of errors includes those resulting from invalid operation types, invalid object hierarchies, and invalid naming or value elements. However, some schema errors may go undetected because, as previously noted, the router does not validate the request against an XML schema.
In the following example, the client application has requested a <Set> operation specifying an object <ExternalRoutes> that does not exist at this location in the Border Gateway Protocol (BGP) component hierarchy. This example illustrates the format and placement of the error attributes.
Note The actual error codes and messages may be different than those shown in the example.
Sample XML Client Request Specifying an Invalid Object Hierarchy
<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
<Get>
<Configuration>
<BGP MajorVersion="24" MinorVersion="0">
<AS>
<Naming>
<AS>0</AS>
</Naming>
<FourByteAS>
<Naming><AS>3</AS></Naming>
<DefaultVRF>
<Global>
<ExternalRoutes>10</ExternalRoutes>
</Global>
</DefaultVRF>
</FourByteAS>
</AS>
</BGP>
</Configuration>
</Set>
</Request>
Sample XML Response from the Router
<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0">
<Set xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ErrorCode="0x4368a400"
ErrorMsg="'XML Service Library' detected the 'warning'
condition 'An error was encountered in the XML beneath this operation
tag'">
<Configuration>
<BGP MajorVersion="24" MinorVersion="0"
<AS>
<Naming>
<AS>0</AS>
</Naming>
<FourByteAS>
<Naming><AS>3</AS></Naming>
<DefaultVRF>
<Global ErrorCode="0x4368a400" ErrorMsg="'XMLMDA' detected the 'warning' condition '
The XML request does not conform to the schema. A child element of
the element on which this error appears is invalid. No such child
element name exists at this location in the schema. Please check
the request against the schema.'"/>
</DefaultVRF>
</AS>
</BGP>
</Configuration>
</Set>
<ResultSummary ErrorCount="0"/>
</Response>
The following example also illustrates a schema error. In this case, the client application has requested a <Set> operation specifying a value for the <GracefulRestartTime> object that is not within the range of valid values for this item.
Sample XML Request Specifying an Invalid Object Value Range
<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
<Set>
<Configuration>
<BGP MajorVersion="24" MinorVersion="0">
<AS>
<Naming>
<AS>0</AS>
</Naming>
<FourByteAS>
<Naming><AS>3</AS></Naming>
<DefaultVRF>
<Global>
<GracefulRestartTime>6000</GracefulRestartTime>
</Global>
</DefaultVRF>
</FourByteAS>
</AS>
</BGP>
</Configuration>
</Set>
</Request>
Sample XML Response from the Router
<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0">
<Set xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ErrorCode="0x4368a800"
ErrorMsg="'XML Service Library' detected the 'warning'
condition 'An error was encountered in the XML beneath this operation
tag'">
<Configuration>
<BGP MajorVersion="24" MinorVersion="0">
<AS>
<Naming>
<AS>0</AS>
</Naming>
<FourByteAS>
<Naming><AS>3</AS></Naming>
<DefaultVRF>
<Global>
<GracefulRestartTime ErrorCode="0x4368a800" ErrorMsg='
XMLMDA' detected the 'warning' condition '
The XML request does not conform to the schema. The character data
contained in the element on which this error appears (or one of its
child elements) does not conform to the XML schema for its datatype.
Please check the request against the schema.'"/>
</Global>
</DefaultVRF>
</AS>
</BGP>
</Configuration>
</Set>
<ResultSummary ErrorCount="1"/>
</Response>
Operation Processing Errors
Operation processing errors include errors encountered during the processing of an operation, typically as a result of committing the target configuration after previous <Set> or <Delete> operations. While processing an operation, errors are returned from Configuration Manager and the infrastructure, failed authorization attempts occur, and "invalid configuration errors" are returned from the back-end
Cisco IOS XR applications.
The following example illustrates an operation processing error resulting from a <GetNext> request specifying an unrecognized iterator ID:
Sample XML Client Request and Processing Error
<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
<GetNext IteratorID="1" Abort="true"/>
</Request>
Sample XML Response from the Router
<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0" ErrorCode="0xa367a800" ErrorMsg="'
XML Service Library' detected the 'fatal' condition 'The XML
Infrastructure has been provided with an iterator ID which is not recognized. The
iterator is either invalid or has timed out.'"/>
Error Codes and Messages
The error codes and messages returned from the router may originate in any one of several components.
The error codes (cerrnos) returned from these layers are 32-bit integer values. In general, for a given error condition, the error message returned in the XML is the same as the error message displayed on the CLI.
Feedback