Error Handling

This guide explains how error handling works in Phonexia microservices, including the standard gRPC error model and the richer error model implementation with detailed error information.

Overview

gRPC provides two approaches to error handling:

1. Standard Error Model: Returns basic status codes with an optional error message
2. Richer Error Model: Extends the standard model with structured error details using Protocol Buffers

Phonexia microservices use both approaches, with some services like Speech to Text implementing the richer error model to provide more detailed, machine-readable error information.

Standard error model

Status codes

When a gRPC call fails, the server returns one of the standard gRPC status codes along with an optional error message. Common status codes include:

• OK (0): Success
• INVALID_ARGUMENT (3): Client specified an invalid argument
• NOT_FOUND (5): Requested entity not found
• RESOURCE_EXHAUSTED (8): Resource has been exhausted (e.g., no instances available)
• FAILED_PRECONDITION (9): Operation rejected because system is not in required state
• INTERNAL (13): Internal server error
• UNAVAILABLE (14): Service is currently unavailable

Example

A basic error response contains:

• Status code: Indicates the type of error
• Error message: Human-readable description of what went wrong

code: INVALID_ARGUMENT
message: "Option 'max_speakers' must be larger than 0"

Richer error model

The richer error model extends the standard model by allowing servers to include additional structured error details in the response. These details are expressed as Protocol Buffer messages in the google.rpc.Status.details field.

Benefits

• Machine-readable: Clients can programmatically handle specific error conditions
• Structured information: Detailed context about what went wrong and how to fix it
• Standardized: Uses well-defined Protocol Buffer messages from google.rpc.error_details.proto

Error details messages

The richer model uses standardized error detail message types defined in google.rpc.error_details.proto:

ErrorInfo

The ErrorInfo message is the primary way to provide machine-readable error information. Following Google's API Improvement Proposal 193, all errors using the richer model include an ErrorInfo message.

message ErrorInfo {
  string reason = 1;    // UPPER_SNAKE_CASE error identifier
  string domain = 2;    // Service domain (e.g., "speech-to-text.phonexia")
  map<string, string> metadata = 3;  // Additional context
}

• reason: A constant identifier for the error type (e.g., UNSUPPORTED_GRAPHEME, EMPTY_FIELD)
• domain: Identifies the service that generated the error
• metadata: Key-value pairs providing additional context

BadRequest

The BadRequest message describes violations in a client request, focusing on syntactic aspects:

message BadRequest {
  message FieldViolation {
    string field = 1;        // Path to the invalid field
    string description = 2;   // Human-readable error description
    string reason = 3;        // Machine-readable error reason
  }
  repeated FieldViolation field_violations = 1;
}

• field: Identifies which field in the request is invalid (e.g., config.additional_words[0].spelling)
• description: Explains why the field is invalid
• reason: Machine-readable identifier matching the convention from ErrorInfo

Implementation in Speech to Text

The Phonexia Speech to Text microservice implements the richer error model to provide detailed validation feedback. When validation fails, the response always includes:

1. ErrorInfo: Top-level error context with reason and domain
2. BadRequest: Field-level validation errors with specific violations

Error structure

google.rpc.Status {
  code: INVALID_ARGUMENT
  message: "Invalid argument"
  details: [
    ErrorInfo {
      reason: "INPUT_ERROR"
      domain: "speech-to-text.phonexia"
    },
    BadRequest {
      field_violations: [
        {
          field: "config.preferred_phrases[0]"
          description: "Invalid grapheme 'ř' in preferred phrase 'křeček'"
          reason: "UNSUPPORTED_GRAPHEME"
        }
      ]
    }
  ]
}

Supported error reasons

The Speech to Text service defines the following error reasons:

ErrorInfo reasons

Reason	Description
INPUT_ERROR	General input validation error

BadRequest field violation reasons

Reason	Description
UNSUPPORTED_GRAPHEME	Character not supported by the model
UNSUPPORTED_PHONEME	Phoneme not supported by the model
EMPTY_FIELD	Required field is empty or missing
PRONUNCIATION_TOO_SHORT	Pronunciation contains fewer than 3 phonemes

Field path format

Field violations use dot notation with array indices to identify the exact location of the error:

• audio: Error in the audio field
• config.additional_words[0].spelling: Error in the spelling of the first additional word
• config.additional_words[2].pronunciations[1]: Error in the second pronunciation of the third additional word
• config.preferred_phrases[5]: Error in the sixth preferred phrase

Failed Validation Examples

Example 1: invalid grapheme in preferred phrase

When a preferred phrase contains an unsupported character:

Request:

{
  "audio": { "content": "..." },
  "config": {
    "preferred_phrases": ["hello world", "café"]
  }
}

Error Response:

code: INVALID_ARGUMENT
message: "Invalid argument"
details: [
  ErrorInfo {
    reason: "INPUT_ERROR"
    domain: "speech-to-text.phonexia"
  },
  BadRequest {
    field_violations: [
      {
        field: "config.preferred_phrases[1]"
        description: "Invalid grapheme 'é' in preferred phrase 'café'"
        reason: "UNSUPPORTED_GRAPHEME"
      }
    ]
  }
]

Example 2: empty additional word spelling

When an additional word has no spelling provided:

Error Response:

code: INVALID_ARGUMENT
message: "Arguments provided on the input are invalid"
details: [
  ErrorInfo {
    reason: "INPUT_ERROR"
    domain: "speech-to-text.phonexia"
  },
  BadRequest {
    field_violations: [
      {
        field: "config.additional_words[0].spelling"
        description: "Additional word spelling cannot be empty"
        reason: "EMPTY_FIELD"
      }
    ]
  }
]

Example 3: invalid phoneme in pronunciation

When a pronunciation contains an unsupported phoneme:

Error Response:

code: INVALID_ARGUMENT
message: "Invalid argument"
details: [
  ErrorInfo {
    reason: "INPUT_ERROR"
    domain: "speech-to-text.phonexia"
  },
  BadRequest {
    field_violations: [
      {
        field: "config.additional_words[0].pronunciations[0]"
        description: "Invalid phoneme 'zh' in pronunciation 'zh ay' in a word 'chai'"
        reason: "UNSUPPORTED_PHONEME"
      }
    ]
  }
]

Example 4: pronunciation too short

When a pronunciation contains fewer than 3 phonemes:

Error Response:

code: INVALID_ARGUMENT
message: "Invalid argument"
details: [
  ErrorInfo {
    reason: "INPUT_ERROR"
    domain: "speech-to-text.phonexia"
  },
  BadRequest {
    field_violations: [
      {
        field: "config.additional_words[0].pronunciations[0]"
        description: "Pronunciation 'k ae' in a word 'cat' must contain at least 3 phonemes"
        reason: "PRONUNCIATION_TOO_SHORT"
      }
    ]
  }
]

Example 5: multiple violations

When multiple fields have errors, all violations are reported together:

Error Response:

code: INVALID_ARGUMENT
message: "Invalid argument"
details: [
  ErrorInfo {
    reason: "INPUT_ERROR"
    domain: "speech-to-text.phonexia"
  },
  BadRequest {
    field_violations: [
      {
        field: "config.additional_words[0].spelling"
        description: "Additional word spelling cannot be empty"
        reason: "EMPTY_FIELD"
      },
      {
        field: "config.preferred_phrases[2]"
        description: "Invalid grapheme 'ñ' in preferred phrase 'mañana'"
        reason: "UNSUPPORTED_GRAPHEME"
      }
    ]
  }
]

References

• gRPC Error Handling Guide
• Google API Error Model (AIP-193)
• google.rpc.error_details.proto
• gRPC Status Codes