Best practices

STT errors and troubleshooting

How the STT API reports errors on the synchronous and WebSocket endpoints, the common gRPC status codes, and what to check when transcription fails.

Error format

Errors follow the standard gRPC status format.

Authentication error

json

{
  "code": 16,
  "message": "Unauthenticated: invalid or missing API key.",
  "details": []
}

Invalid request

json

{
  "code": 3,
  "message": "Unsupported audio encoding.",
  "details": []
}

Common gRPC status codes

Code	Name	Description
`3`	`INVALID_ARGUMENT`	Invalid or missing request field (encoding, model ID, audio data)
`8`	`RESOURCE_EXHAUSTED`	Too many concurrent requests (rate limit)
`16`	`UNAUTHENTICATED`	Invalid or missing API key

Streaming (WebSocket) errors

On the streaming endpoint, errors arrive as a frame with a top-level error key using the same status format:

json

{
  "error": {
    "code": 3,
    "message": "invalid transcribe config: unsupported audio encoding"
  }
}

A malformed first message (for example, a config not wrapped in transcribeConfig) currently closes the socket with WebSocket close code 1005 and no error frame. If your connection closes silently with no transcripts, check the shape of your first message.

Troubleshooting

Issue	What to check
No transcript	API key, audio encoding matches request, valid audio file
`UNAUTHENTICATED`	`INWORLD_API_KEY` set correctly and not expired in Portal
`INVALID_ARGUMENT`	`audioEncoding` matches the actual format (LINEAR16 for raw PCM, MP3 for MP3, etc.)
Poor quality	Use 16 kHz sample rate (8 kHz telephony audio has fewer data points and will produce lower-quality results); ensure clear speech
Large file failures	Split or compress (e.g. MP3/OGG_OPUS); respect upload size limits
No Voice Profile	Ensure `voiceProfileConfig.enableVoiceProfile` is set to `true` in your request

For more help, see the Inworld Discord community.