Cisco Finesse API Errors

Error codes for Cisco Finesse are categorized as follows:

  • 4xx—Client-related error

  • 5xx—Server-related error

Each error includes a failure response, error type, error message, and error data. The following is an example of a failure message format:
Code Snippet
Copy
<ApiErrors>
   <ApiError>
      <ErrorType>Authentication Failure</ErrorType>
      <ErrorMessage>UNAUTHORIZED</ErrorMessage>
      <ErrorData>jsmith</ErrorData>
   </ApiError>
</ApiErrors>

In addition to Cisco Finesse API errors, a response may return a CTI error or an HTTP error.

Note

This document contains information about error type and error message. You can find information about error data values for most User and Dialog errors in the following documents:

For Finesse deployments with Unified CCE, see the CTI Server Message Reference Guide for Cisco Unified Contact Center Enterprise, which you can find at https://developer.cisco.com/site/cti-protocol/documentation/.

For Finesse deployments with Unified CCX, see the https://developer.cisco.com/docs/contact-center-express/#!cti-protocol-dev-guide.

HTTP Errors

All HTTP errors are returned as HTTP 1.1 Status Codes. Errors that might be for Finesse-specific events are listed below:
500 Internal Server Error
Finesse Web Services returns 500 if the CTI connection is lost but the loss is not yet detected by automated means.

  • 500 - DB_RUNTIME_EXCEPTION (database error, but the database is thought to be operational)

  • 500 - RUNTIME_EXCEPTION (a non-database error)

  • 500 - AWS_SERVICE_UNAVAILABLE (AWS not operational)

503 Service Unavailable
If Finesse is in PARTIAL_SERVICE or OUT_OF_SERVICE, it returns 503 for all requests. If any dependent service goes down, Finesse goes to OUT_OF_SERVICE state (for example, if the Cisco Finesse Notification Service is down).This error is due to a temporary outage or overloading condition. A retry after several seconds is likely to succeed. For example, the system returns 503 when the system is just starting up and when the system is trying to connect to the CTI server.

Peripheral Error Codes

Cisco Finesse, Release 12.5(1) introduces peripheral error codes for CTI operations, which provide a more detailed description of the error scenario. The newly added parameters are:

  • peripheralErrorCode

  • peripheralErrorMsg

  • peripheralErrorText

Example:

Code Snippet
Copy<ApiErrors>
    <ApiError>
        <ErrorType>Service Unavailable</ErrorType>
        <ErrorData></ErrorData>
        <ErrorMessage>SERVER_OUT_OF_SERVICE</ErrorMessage>
        <peripheralErrorCode>13036</peripheralErrorCode>
        <peripheralErrorMsg>PERERR_GW_E_JTAPIOBJ_PERFORMANSWERCALL_NO_TERMINAL_CONNECTION</peripheralErrorMsg>
        <peripheralErrorText>The routine performAnswerCall in class JTapiObj got a null connection from a call to 'findTerminalConnection'</peripheralErrorText>
    </ApiError>
</ApiErrors>

For more information, see Cisco IPCC Error Codes at https://www.cisco.com/c/en/us/support/docs/voice-unified-communications/unified-contact-center-enterprise/26142-error-codes.html.