RPC gRPC messages
These messages are part of the nuance.rpc package referenced by other Nuance methods. They provide additional information about the requests.
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 the local language. |
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, e.g. 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. |
nuance.rpc.Hyperlink
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.
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.