RPC status messages

Messages that are part of the nuance.rpc package are used for RPC status and error information.

  RPC proto file fields  

nuance.rpc.Status

Status messages for requests used by Nuance APIs. The status_code field is mandatory, all others are optional.

Field Type Description
status_code StatusCode Mandatory. Status code, an enum value.
status_sub_code int32 Application-specific status sub-code.
http_trans_code int32 HTTP status code for the transcoder, if applicable.
request_info RequestInfo Information about the original request.
status_message LocalizedMessage Message providing the details of this status in a language other than English.
help_info HelpInfo Help message providing possible user actions.
field_violations FieldViolation Repeated. Set of request field violations.
retry_info RetryInfo Retry information.
status_details StatusDetail Repeated. Detailed status messages.

This reports an ongoing job, combining job status with request status:

2021-04-05 16:41:28,369 INFO : Received response: job_status_update {
  job_id: "c21b0be0-964e-11eb-9e4a-5fb8e278d1ad"
  status: JOB_STATUS_PROCESSING
}
request_status {
  status_code: OK
  http_trans_code: 200
}

2021-04-05 16:41:28,896 INFO : new server stream count 2
2021-04-05 16:41:28,896 INFO : Received response: job_status_update {
  job_id: "c21b0be0-964e-11eb-9e4a-5fb8e278d1ad"
  status: JOB_STATUS_COMPLETE
}
request_status {
  status_code: OK
  http_trans_code: 200
}

This reports an error in a JSON file:

2021-04-05 16:34:55,874 INFO : Received response: request_status {
  status_code: BAD_REQUEST
  status_sub_code: 7
  http_trans_code: 400
  status_message {
    locale: "en-US"
    message: "Invalid wordset content Unexpected token c in JSON at position 5"
    message_resource_id: "7"
  }
}

This reports an existing object:

2021-04-05 17:37:41,977 INFO : Received response: request_status {
  status_code: ALREADY_EXISTS
  status_sub_code: 10
  http_trans_code: 200
  status_message {
    locale: "en-US"
    message: "Compiled wordset already available for artifact reference urn:nuance-mix:tag:wordset:lang/names-places/places-compiled-ws/eng-USA/mix.asr"
    message_resource_id: "10"
  }
}

nuance.rpc.StatusCode

Status codes related to requests used by Nuance APIs.

Name Number Description
UNSPECIFIED 0 Unspecified status.
OK 1 Success.
BAD_REQUEST 2 Invalid message type: the server cannot understand the request.
INVALID_REQUEST 3 The request has an invalid value, is missing a mandatory field, etc.
CANCELLED_CLIENT 4 Operation terminated by client. The remote system may have changed.
CANCELLED_SERVER 5 Operation terminated by server. The remote system may have changed.
DEADLINE_EXCEEDED 6 The deadline set for the operation has expired.
NOT_AUTHORIZED 7 The client does not have authorization to perform the operation.
PERMISSION_DENIED 8 The client does not have authorization to perform the operation on the requested entities.
NOT_FOUND 9 The requested entity was not found.
ALREADY_EXISTS 10 Cannot create entity as it already exists.
NOT_IMPLEMENTED 11 Unsupported operation or parameter, for example an unsupported media type.
UNKNOWN 15 Result does not map to any defined status. Other response values may provide request-specific additional information.

The following status codes are less frequently used.

Name Number Description
TOO_LARGE 51 A field is too large to be processed due to technical limitations, for example a large audio or other binary block. For arbitrary limitations (for example name must be n characters or less), use INVALID_REQUEST.
BUSY 52 The server understood the request but could not process it due to lack of resources. Retry the request as is later.
OBSOLETE 53 A message type in the request is no longer supported.
RATE_EXCEEDED 54 Similar to BUSY. The client has exceeded the limit of operations per time unit. Retry request as is later.
QUOTA_EXCEEDED 55 The client has exceeded quotas related to licensing or payment. See your client representative for additional quotas.
INTERNAL_ERROR 56 An internal system error occurred while processing the request.

nuance.rpc.RequestInfo

Information about the request that resulted in an error. This message is particularly useful in streaming scenarios where the correlation between the request and response is not so obvious.

Field Type Description
request_id string Identifier of the original request, for example, its OpenTracing id.
request_data string Relevant free format data from the original request, for troubleshooting.
additional_request_data map<string,string> Map of key,value pairs of free format data from the request.

nuance.rpc.LocalizedMessage

A help message in the language (locale) specified. The default locale is provided by the server, for example the browser’s preferred language or a user-specific locale.

All Nuance gRPC APIs that want the server to provide localized errors must accept the HTTP “Accept-Language” header or application-specific language settings, if supported.

Field Type Description
locale string The language and region used for the message, for example en-US.
message string The message in the locale specified.
message_resource_id string A message identifier, allowing related messages to be provided if needed.

nuance.rpc.HelpInfo

A reference to a help document that may be shown to end users to allow them to take action based on the error or status response. For example, if the request contained a numerical value that is out of range, this message may point to the documentation that states the valid range.

Field Type Description
links Hyperlink Repeated. Set of hypertext links related to the context of the enclosing message.

Details about the hypertext link containing information related to the message.

Field Type Description
description LocalizedMessage A description of the link in a specific language (locale).
By default, the server handling the URL manages language selection and detection.
url string The URL to offer to the client, containing help information. If a description is present, this URL should use (or offer) the same locale.

nuance.rpc.FieldViolation

Information about a request field or fields containing errors.

Field Type Description
field string The name of the request field in violation as package.type[.type].field.
rel_field string Repeated. Repeated. The names of related fields in violation as package.type[.type].field.
user_message LocalizedMessage An error message in a language other than English.
message string An error message in American English.
invalid_value string The invalid value of the field in violation. (Convert non-string data types to string.)
violation ViolationType The reason (enum) a field is invalid. Can be used for automated error handling by the client.

nuance.rpc.ViolationType

The error type of the request field, as a keyword.

Name Number Description
MANDATORY_FIELD_MISSING 0 A required field was not provided.
FIELD_CONFLICT 1 A field is invalid due to the value of another field.
OUT_OF_RANGE 2 A field value is outside the specified range.
INVALID_FORMAT 3 A field value is not in the correct format.
TOO_SHORT 4 A text field value is too short.
TOO_LONG 5 A text field value is too long.
OTHER 64 Violation type is not otherwise listed.
UNSPECIFIED 99 Violation type was not set.

nuance.rpc.RetryInfo

How quickly clients may retry the request for requests that allow retries. Failure to respect this delay may indicate a misbehaving client.

Field Type Description
retry_delay_ms int32 Clients must wait at least this long between retrying the same request.

nuance.rpc.StatusDetail

A status message may have additional details, usually a list of underlying causes of an error. In contrast to field violations, which point to the fields in the original request, status details are not usually directly connected with the request parameters.

Field Type Description
message string The message text in American English.
user_message LocalizedMessage The message text in a language other than English.
extras map<string,string> Map of key,value pairs of additional application-specific information.

Scalar value types

The data types in the proto files are mapped to equivalent types in the generated client stub files.

Scalar data types
Proto Notes C++ Java Python
double double double float
float float float float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers. If your field is likely to have negative values, use sint32 instead. int32 int int
int64 Uses variable-length encoding. Inefficient for encoding negative numbers. If your field is likely to have negative values, use sint64 instead. int64 long int/long
uint32 Uses variable-length encoding. uint32 int int/long
uint64 Uses variable-length encoding. uint64 long int/long
sint32 Uses variable-length encoding. Signed int value. These encode negative numbers more efficiently than regular int32s. int32 int int
sint64 Uses variable-length encoding. Signed int value. These encode negative numbers more efficiently than regular int64s. int64 long int/long
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long
sfixed32 Always four bytes. int32 int int
sfixed64 Always eight bytes. int64 long int/long
bool bool boolean boolean
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode
bytes May contain any arbitrary sequence of bytes. string ByteString str