Product Documentation

Error Handling

Jun 14, 2016
In case of a failed request, NITRO provides the required information through the HTTP status code and in the response header and response payload.

Error in a Single Resource Operation

The response of a single erroneous operation is as follows:

HTTP Status Code
4xx <string> (for general HTTP errors) or 5xx <string> (for NetScaler-specific errors)
Response Header
Content-Type:application/vnd.com.citrix.netscaler.error+json
Response Payload
{ 
    errorcode: <Error code> 
    message: "<Error message>" 
    severity: "ERROR" 
}

Error in a Bulk Operation

When there is a failure in one of the bulk operations, the response payload gives a combination of success and failure (depends on the value set for X-NITRO-ONERROR in the request header).

HTTP Status Code
207 Multi Status
Response Header
Content-Type:application/vnd.com.citrix.netscaler.error_list+json
Response Payload when X-NITRO-ONERROR is set to continue
When the first operation fails, the request is not terminated. The response payload shows the error details of the failed operation and the success status of the other operations.
{ 
    "errorcode": 1243, 
    "message": "Bulk operation failed", 
    "severity": "ERROR", 
    "response": 
    [ 
        { 
            "errorcode": 273, 
            "message": "Resource already exists", 
            "severity": "ERROR" 
        }, 
        { 
            "errorcode": 0, 
            "message": "Done", 
            "severity": "NONE" 
        } 
    ] 
}
Response Payload when X-NITRO-ONERROR is set to exit
When the first operation fails, the request is terminated. The response payload only shows the error details of the failed operation.
{ 
    "errorcode": 1243, 
    "message": "Bulk operation failed", 
    "severity": "ERROR", 
    "response": 
    [ 
        { 
            "errorcode": 273, 
            "message": "Resource already exists", 
            "severity": "ERROR" 
        } 
    ] 
}

Warnings in NITRO Operations

Warnings can be captured by specifying the "warning" query parameter as "yes" when performing any NITRO operation. For example, to get warnings while connecting to the NetScaler appliance, the URL is as follows:

http://<netscaler-ip-address>/nitro/v1/config/login?warning=yes

If there are any warnings, the response is as follows:

HTTP Status Code
209 X-NITRO-WARNING
Response Header
Content-Type:application/vnd.com.citrix.netscaler.warning+json
Response Payload
{ 
    errorcode: <Code> 
    message: "<Message>" 
    severity: "WARNING" 
}