Troubleshooting

Match a HUMAIN Voice symptom to its likely cause and the fix for connection, audio, batch, streaming, text-to-speech, and Voice Agent problems.

Connection and authentication

SymptomLikely causeFix
401 AUTH_UNAUTHORIZEDKey missing, mistyped, revoked, or expired.Send API_KEY as x-api-key; see Authentication errors.
401 with a key that works elsewhereKey issued for another environment.Use the key with its own API_URL; see Get an API key.
403 AUTH_FORBIDDENKey lacks the scope for this operation.Check the key's Scopes; see Authentication errors.
403 with no ErrorResponse bodyA gateway rejected the request.Check API_URL, route, headers, and on Socket.IO the Origin header; see Authentication errors.
Socket.IO connect_error or no connect eventWrong path, missing Origin, or polling transport.Use /socket.io, Origin, and WebSocket; see Send the key: Socket.IO.
JavaScript process never exits after a rejected keySDK 0.18.1 keeps reconnecting after connect() rejects.Catch the error and exit explicitly with process.exit(1); see Configure a client.

Audio format

SymptomLikely causeFix
Realtime text is empty, garbled, too fast, or too slowWAV/MP3 bytes or the wrong rate sent as PCM.Convert to PCM16 LE, 16 kHz, mono; see Prepare audio.
8 kHz phone audio transcribes poorly in realtimeRealtime expects 16 kHz.Convert it with the Prepare audio command.
Poor results on 8 kHz Arabic call recordings in batchThe model isn't the telephony model.Use nida_8k_ar; see Choosing a model by use case.
Fast ASR_UNSUPPORTED_CODEC, or MP4 failsUnsupported container, or MP4 moov atom at the end.Re-encode to a listed format with moov first; see Audio formats.
Batch 422 VALIDATION_FILE_CORRUPTCorrupt, empty, or unsupported file.Check the file decodes with ffmpeg, then resubmit.

Batch jobs

SymptomLikely causeFix
Job stays queued or processingLong audio or busy capacity.Poll within one overall deadline; see Batch is a job.
BatchTranscribeTimeoutErrorPolling ran past the SDK timeout.Raise the timeout or poll the job ID; see Handle failures.
Second read returns clearedThe first read cleared the result.Poll with save_result=true; see Read the result again.
Job reaches failedProcessing failed.Resubmit once; if it fails again, contact support with the job ID.
429 RATE_LIMIT_EXCEEDED on submitBatch audio capacity used up.Back off; see Capacity responses.
422 AUDIO_DURATION_EXCEEDEDAudio is over the 4-hour submission limit.Split the recording; see Batch limits.
Submit timed out or returned 500A job may exist.Don't resubmit automatically; see Retries and duplicates.

Streaming results

SymptomLikely causeFix
Captions repeat provisional textEvery result was appended.Replace provisional text per id; see Streaming results.
Last words missing; no is_finalclose() returned after its 1-second default.Call close(5); see End the stream.
Only the first utterance in captionsA helper dropped finals that share a seq.Collect the words of each final result yourself; see Subtitles.
Speaker labels differ between batch and streamingLabels are opaque, result-relative strings.Don't parse or compare labels; see Speaker timelines.
One person gets two live speaker labelsLive diarization can over-split.Merge labels in your app; see Speaker timelines.
Stream dropped mid-sessionNo resume or replay.Keep committed text and start a new stream; see Recover.

Text to speech

SymptomLikely causeFix
Saved file won't playSDK output is raw PCM, not WAV.Add a WAV header; see Save speech to a WAV file.
Streamed audio is silent or noisy in ffplayWrong player format.Pipe to ffplay -f s16le -ar 24000 -ch_layout mono -; see Play speech.
HTTP tts output isn't playableFrame headers sit inside the streaming audio.Use the SDK or Socket.IO, or call POST /v1/audio/speech for one complete playable file; see also HTTP text to speech.
TTS_VOICE_NOT_FOUNDvoice_id from another environment, or a label.Look up the profile id; see Voice list.
TTS_INPUT_NOT_ALLOWEDContent policy rejected the text.Change the text; see Text-to-speech codes.
TTS_MODERATION_UNAVAILABLEModeration couldn't decide.Back off and retry; see Retrying safely.
CHARACTER_COUNT_EXCEEDEDText over your plan's limit.Split the text; see TTS limits.

Voice agent

SymptomLikely causeFix
Session request returns 400Unknown field, invalid value, or a variable without a value.Fix each field in data.errors; see Validation errors.
The call ends with user_never_joinedThe token was used after expires_at, about a minute after the request.Start the session when the user clicks, and connect right away.
MIC_PERMISSION_DENIEDThe user refused the microphone, or the page isn't on HTTPS or localhost.Serve the page over HTTPS and ask the user to allow the microphone.
The agent's status is ready but it can't be heardThe browser blocked audio that didn't start from a click.Start the call from a click, or call startAudio() from onAudioBlocked; see Browser SDK.
CONNECTION_FAILED on an office or hotel network onlyThe network blocks WebRTC traffic.Allow outbound UDP and TCP 443 to the server_url host.
The agent says it can't do something your tool handlesNo handler for the tool, or the handler threw.Check onError for CLIENT_TOOL_NOT_HANDLED or CLIENT_TOOL_FAILED; see Client tools.
Session request returns 403Voice Agent isn't enabled for your account yet.Contact support.
Session request returns 429All concurrent calls of your plan are live, or the daily minutes are used up.Wait for Retry-After; see Plan limits.

Contact support

Send your HUMAIN contact:

  • The time of the failure, with timezone.
  • The environment's API_URL.
  • The request, job, or stream ID.
  • The error code and HTTP status.
  • The SDK and its version, such as @humain-voice/[email protected].
  • The smallest code sample that reproduces the problem.

Never send your API key. Send customer audio or text only if support asks for it.

Next steps

On this page