Status codes

A single Nuance Recognizer service provides a Recognize method and a DTMFRecognize method, both supporting bi-directional streaming of requests and responses.

Nuance Recognizer returns standard gRPC error  and HTTP codes as part of its responses.

Request procedure

First, the client provides a recognition request message with parameters indicating at least one grammar resource, and additionally for a speech recognition, what audio format and language to use. Optionally, it can also include parameters to control various aspects of the recognition, and arbitrary client data to be injected into call recording for reference in offline tuning workflows.

In response to this recognition request message, NRaaS returns a status message confirming the outcome of the request. When the recognition initializes successfully, the message is 200 OK.

Status messages can also be HTTP-aligned status codes. A failure to begin recognizing returns a 4xx or 5xx status.

Example 200 OK status response:

  status: {
    code: 200
    message: 'OK'
  }

When a 200 OK status is received, the client can then send one or more messages bearing binary audio samples in the format indicated in the recognize initialization message. During a speech recognition, the server responds with messages indicating the detection of the start and end of speech in the audio. Once a recognition is completed the server will send a result message indicating a normal completion or an error status message (4xx/5xx) if an error is encountered and the recognition failed. If available, the status response includes a details line with a longer description of the status.

Example full status response:

  status: {
    code: [HTTP-style return code: 100, 200, 4xx, or 5xx as appropriate.]
    message: '[Brief description of the status.]'
    details: '[Longer description if available.]'
  }

Causes of termination

The reasons for a speech or DTMF recognition terminating can include:

Speech recognition termination:

  • Client ends its message stream to the server.
  • Client cancels the RPC (remote procedure call).
  • Server detects the end of speech.
  • Server observes non-speech samples corresponding to the no_input_timeout_ms value.
  • Server observes speech samples resulting in a recognition timeout corresponding to complete_timeout_ms, incomplete_timeout_ms or max_speech_timeout_ms value.
  • Server observes no audio (or any message) is received for a server-configured inactivity timeout.
  • Server observes the recognition duration exceeds a server-configured session timeout.
  • Server encounters an error.

DTMF recognition termination:

  • Client ends its message stream to the server.
  • Client cancels the RPC.
  • Server observes no DTMF message after the initialization message for a duration exceeding to the no_input_timeout_ms value.
  • Server observes no subsequent DTMF message for a duration exceeding the dtmf_interdigit_timeout_ms value.
  • Server observes no terminating character DTMF message is received after the start of the recognition for a duration corresponding to the dtmf_term_timeout_ms value.
  • Server observes the terminating DTMF character.
  • Server observes the recognition duration exceeds a server-configured session timeout.
  • Server encounters an error.

If the client cancels the RPC, no further messages are received from the server. If the server encounters an error, it attempts to send a final error status and then cancels the RPC.

Status codes

Nuance Recognizer uses the HTTP status codes listed below. In general, values in the 400 range indicate an error in the request that your client app sent. Values in the 500 range indicate an internal error within Nuance Recognizer or another service.

Status codes table
Code Message Indicates
200 OK Recognition parameters and resources were accepted and successfully configured. Client can proceed to send audio data. This status is also returned in response to a Control start_timers message, which starts the no-input timer manually when automatic start of the timer is disabled by the stall_timers recognition flag in the recognition initialization message.
400 Bad request A malformed or unsupported client request was rejected.
403 Forbidden The request could not be authorized, when authorization is required.
404 No-Input Timeout (audio silence) No utterance was detected in the audio stream for a number of samples corresponding to no_input_timeout_ms. This may occur if the audio does not contain anything resembling speech. In a DTMF recognition, no DTMF message was received after the initialization for a duration corresponding to no_input_timeout_ms.
408 No-Input Timeout (no audio received) Excessive stall in sending audio data.
413 Too much speech Recognition of utterance samples reached a duration corresponding to recognition_timeout_ms.
418 Session Timeout The duration of the recognition exceeded the server-configured session timeout.
419 No Active Resources This status can be returned if the client tries to perform a speech recognition (invokes the Recognize API) but provides DTMF-only grammar resources in the recognition initialization message. The recognizer will fail to initiate the recognition because there are no active speech grammar resources and will return this status. For DTMF-only recognitions, the DTMFRecognize API must be used.
500 Internal server error A serious error occurred that prevented the request from completing normally.