API Guides

Errors and limits

Look up every HUMAIN Voice limit and error code, including Voice Agent sessions, and retry failed requests without duplicating work.

Error response shape

HTTP routes return an ErrorResponse body. Socket.IO routes emit an error event that carries message instead of error and detail. Branch on code and retryable, never on message text.

FieldHTTPSocket.IOMeaning
codeYesYesMachine-readable error code.
retryableYesYesWhether a retry of this request can succeed.
timestampYesYesServer time of the error.
dataYesYesOn limit rejections: limit, observed, unit, bound. Batch 429 carries { capacity } instead.
error, detailYesNoLegacy identifier and human-readable text.
message401 missing key onlyYes (always)Human-readable text.
job_id / idjob_ididJob or stream UUID.
request_idBatchNoTrace ID for support requests.
retry_after_secondsNo (Retry-After header)YesSeconds to wait before retrying.
reason, retry_scopeNoASR_STREAM_EXPIRED onlyWhy the stream ended; retry_scope is new_stream.

A batch file that decodes to more than 4 hours returns:

{
  "error": "error.api.error.audio.duration_exceeded",
  "code": "AUDIO_DURATION_EXCEEDED",
  "detail": "error.api.error.audio.duration_exceeded",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z",
  "data": { "limit": 14400, "observed": 18000, "unit": "seconds", "bound": "audio_duration" }
}

Check the HTTP status before parsing a success body, and keep the raw body if JSON parsing fails. On HTTP streaming routes, a failure after output has started ends the 200 response without an error JSON. In the SDKs, batch calls raise BatchTranscribeError with these fields. A failed TTS call keeps only the message, so read code and data in the onError / on_error callback.

Log the code, HTTP status, and request or job ID of every error. Never log API keys or audio.

Limits

Limits are inclusive: a request exactly at the limit succeeds. Deployments can configure other values, so data.limit in the error is authoritative. data.bound names the limit that was hit.

Batch transcription

LimitValueWhen exceededdata.bound
Request size, including multipart overhead512 MiB413 PAYLOAD_TOO_LARGErequest_bytes
Audio files per request1422 FILE_COUNT_EXCEEDEDfile_parts
Multipart parts per request8422 FILE_COUNT_EXCEEDEDmultipart_parts
Decoded audio duration4 h (14,400 s)422 AUDIO_DURATION_EXCEEDEDaudio_duration
Diarization processing duration, all models2,097 s (34 min 57 s), with a 64 MiB decoded-audio capWorker rejects processing after job creationNone
Audio capacityIn audio seconds429 RATE_LIMIT_EXCEEDEDNone; see data.capacity

The 4-hour submission ceiling applies with or without diarization. The diarization worker enforces its separate processing cap after job creation. Acceptance does not guarantee completion; check the job status. Requests rejected at submission create no job. If a request is rejected after the upload starts, it counts 1 audio-second (at most 10) against your batch capacity. You aren't billed for it. A declared Content-Length over 512 MiB is rejected before anything is counted. Send one audio part and nothing after it; a large trailing payload returns 413 with unvalidatable_tail_bytes.

Fast transcription

LimitValueWhen exceededdata.bound
Upload size64 MiBHTTP 413 PAYLOAD_TOO_LARGE. Socket.IO emits the error, then disconnects.fast_audio_bytes
Decoded audio duration1800 s (30 min)HTTP 422 AUDIO_DURATION_EXCEEDED. Socket.IO stays connected.fast_audio_duration

Over HTTP, 64 MiB covers the whole multipart body; over Socket.IO, the media bytes only. A Socket.IO audio_file_upload_success is a receipt: a format or duration error can still follow it.

Realtime transcription

LimitValueWhen exceededdata.bound
Frame size, including the 18-byte header16 MiB per event or POST413 PAYLOAD_TOO_LARGE. Socket.IO emits the error, then disconnects.realtime_asr_frame_bytes
HTTP session idle time900 s408 SESSION_IDLE_TIMEOUTsession_idle
Concurrent streamsPer account, set by your plan429 CONCURRENCY_LIMIT_EXCEEDEDaccount_concurrency_realtime_asr

Concurrency is shared by all API keys of an account, and each workload has its own allowance, so realtime transcription and TTS don't compete.

Live diarization

LimitValueWhen exceededdata.bound
Frame size, including the header16 MiB413 PAYLOAD_TOO_LARGErealtime_diarization_frame_bytes
HTTP POSTs in flight1 per stream UUIDRecords can reach the wrong responseNone

Text to speech

LimitValueWhen exceededdata.bound
text length500 code points (free), 1,000 (standard and enterprise)422 CHARACTER_COUNT_EXCEEDEDtts_input_characters
Voice references1422 VOICE_REFERENCE_COUNT_EXCEEDEDtts_voice_reference_count
Reference transcript500 code points422 CHARACTER_COUNT_EXCEEDEDtts_voice_reference_text_characters
Reference audio size, decoded2 MiB413 PAYLOAD_TOO_LARGEtts_voice_reference_bytes
Reference audio duration15 s422 AUDIO_DURATION_EXCEEDEDtts_voice_reference_duration
HTTP request body16 MiB413 PAYLOAD_TOO_LARGENone
Synthesis time25 s overall504 TTS_DEADLINE_EXCEEDEDNone
Concurrent synthesesPer account, set by your plan429 CONCURRENCY_LIMIT_EXCEEDEDaccount_concurrency_tts

Code points are Unicode code points, including leading and trailing whitespace. TTS limits are checked before any charge.

Voice agent

LimitValueWhen exceededdata.bound
Session request bodySet by HUMAIN Voice; see data.limit413 PAYLOAD_TOO_LARGEagent_request_bytes
Client tools per session16400 VALIDATION_INVALID_PARAMagent_client_tools
Time to join after the requestAbout 60 s (expires_at)The call ends as user_never_joinedNone
Client tool result15 KiB of JSONThe tool call failsNone
Client tool run time120 sThe tool call failsNone
Concurrent callsPer account, set by your plan429 CONCURRENCY_LIMIT_EXCEEDEDaccount_concurrency_agent
Daily minutesPer account, set by your plan; resets at 00:00 UTC429 RATE_LIMIT_EXCEEDEDagent_daily_minutes

Maximum call length and idle time end a call that is already running; see Limits and billing.

Error codes

Socket.IO errors use the same codes without an HTTP status. The Retry column means:

RetryMeaning
YesSafe to retry the same request after a backoff.
After a changeFix the input, key or plan first.
New streamStart a fresh stream or session with a new UUID.
Not automaticallyAn earlier attempt may have succeeded.
—Not documented; follow retryable in the error.

Common codes

CodeHTTPCauseWhat to doRetry
AUTH_UNAUTHORIZED401Missing or invalid API key.Send a valid x-api-key.After a change
AUTH_FORBIDDEN403Key lacks this capability.Use a key with the capability.After a change
METHOD_NOT_ALLOWED405Wrong HTTP method, or the obsolete speaker_id event.Fix the route or event.After a change
VALIDATION_INVALID_FORMAT400Malformed body, frame or reference WAV.Fix the encoding.After a change
VALIDATION_REQUIRED_FIELD400Missing field, empty text or missing start bit.Add the field.After a change
VALIDATION_INVALID_PARAM400Invalid parameter or both voice selectors.Fix the parameter.After a change
VALIDATION_INVALID_UUID400Malformed job ID or voice_id.Send a valid UUID.After a change
VALIDATION_INVALID_LANGUAGE400Unknown language.Use a listed language.After a change
VALIDATION_FILE_CORRUPT400; 422 batchCorrupt or empty audio, or a short frame.Send valid audio.After a change
ASR_MODEL_NOT_FOUND400Batch or fast model not available.Choose a listed model.After a change
PAYLOAD_TOO_LARGE413Over a byte limit (data.bound).Send smaller files or frames.After a change
AUDIO_DURATION_EXCEEDED422Over a duration limit (data.bound).Split the audio.After a change
CREDITS_EXHAUSTED402Account out of credit.Stop and add credit.After a change
BILLING_AUTHORIZATION_UNAVAILABLE503Billing couldn't authorize.Back off and retry.Yes
RATE_LIMIT_EXCEEDED429Batch capacity or per-key request rate; the gateway body may not be an ErrorResponse.Slow down and back off.Yes
CONCURRENCY_LIMIT_EXCEEDED429Too many operations in flight.Wait for Retry-After / retry_after_seconds.Yes
SERVER_INTERNAL500Unexpected server error, or a batch result lookup failed.Retry batch reads made with save_result=true.Yes

A 403 without an ErrorResponse body comes from a gateway: check the URL, route and headers.

Batch codes

CodeHTTPCauseWhat to doRetry
FILE_COUNT_EXCEEDED422Too many files or parts.Send one file.After a change
TRANSCRIPTION_JOB_NOT_FOUND404No job with that UUID.Stop polling; check the stored ID.After a change
ASR_TRANSCRIPTION_FAILED500Submission failed.A job may exist; don't resubmit without a duplicate policy. See Batch REST.Not automatically

Fast, realtime and diarization codes

CodeHTTPCauseWhat to doRetry
ASR_UNSUPPORTED_CODEC400Fast audio isn't AAC, FLAC, MP3, WAV or MP4.Re-encode the file.After a change
ASR_TRANSCRIPTION_FAILED500Recognition failed.Start a new stream.New stream
ASR_STREAM_EXPIREDnoneNo audio within the idle window, or the server lost the stream state (see reason).Start a new stream.New stream
SESSION_BYTE_RATE_EXCEEDED429Audio arrives faster than the session rate.Wait, then resend the same payload (direct API; the SDKs end the stream).Yes
SESSION_SLOTS_EXHAUSTED429Too many open HTTP sessions.Finish sessions, then retry.Yes
SESSION_BYTES_EXCEEDED413Session sent too many bytes; limit in data.limit.Start a new session.New stream
SESSION_DURATION_EXCEEDED422Session open too long; limit in data.limit.Start a new session.New stream
SESSION_IDLE_TIMEOUT408No audio within the idle window.Start a new session.New stream
SESSION_EXPIRED409UUID not started, ended, or started twice.Start a new session.New stream
DIARIZATION_MODEL_NOT_FOUND400Diarization not configured.Contact support.After a change
DIARIZATION_FAILED500Capacity or inference failure.Start a new stream.New stream

Text-to-speech codes

CodeHTTPCauseWhat to doRetry
CHARACTER_COUNT_EXCEEDED422Text or reference transcript too long.Shorten to data.limit.After a change
VOICE_REFERENCE_COUNT_EXCEEDED422More than one reference.Send one.After a change
TTS_VOICE_NOT_FOUND400voice_id isn't available.Pick from the voice list.After a change
TTS_INPUT_NOT_ALLOWED400Content policy rejected the text.Change the text.After a change
TTS_MODERATION_UNAVAILABLE503Moderation couldn't decide.Back off and retry.Yes
TTS_EMOTION_MARKUP_INVALID400A malformed <emotion …> tag, an unclosed span or a mismatched close (Emotion and speaking style).Fix the tag at the offset in message.After a change
TTS_EMOTION_SEGMENT_COUNT_EXCEEDED400Tags split the text into more parts than data.limit. Only on deployments that set segment limits.Use fewer tags.After a change
TTS_EMOTION_SEGMENT_TOO_SHORT400A tagged part is shorter than data.limit characters. Only on deployments that set segment limits.Lengthen the part or remove its tag.After a change
SERVER_DEPENDENCY_FAILURE503Storage outage resolving voice_id.Back off and retry.Yes
TTS_VOICE_RESOLUTION_FAILED500Stored voice data is broken.Choose another voice.After a change
TTS_SYNTHESIS_FAILED500Model or capacity failure.Retry with a fresh UUID.Yes
TTS_DEADLINE_EXCEEDED504Synthesis exceeded 25 s.Discard partial audio and retry.Yes
BILLING_IDEMPOTENCY_CONFLICT409The request UUID was already used for different text, or an Idempotency-Key header was reused under a semantically changed request (the input plus resolved model/voice/format, reordered JSON keys alone are not a change), or the same key value arrived from a different API key of the same account, on POST /v1/audio/speech.Send each distinct request with a new UUID or a new Idempotency-Key.After a change

Voice agent codes

CodeHTTPCauseWhat to doRetry
VALIDATION_INVALID_PARAM400Unknown field, invalid value, or a {{variable}} without a value; each problem is in data.errors.Fix the fields listed by path.After a change
AUTH_SCOPE_MISSING403The key lacks the agent scope; data.required_scope is agent.Enable the agent scope on the key in the console.After a change
AUTH_FORBIDDEN403Voice Agent isn't enabled for the account during the beta, or is turned off.Contact support.After a change
AGENT_SESSION_NOT_FOUND404GET /agent/sessions/{id} with an unknown or malformed ID, or a session of another account.Use a session_id from your own account.After a change
CREDITS_EXHAUSTED402No credit for the first minute, or the account isn't on credit billing.Add credit, or contact support.After a change
CONCURRENCY_LIMIT_EXCEEDED429Your plan's concurrent calls are all live; data.bound is account_concurrency_agent.Wait for Retry-After, or ask the user to try again shortly.Yes
RATE_LIMIT_EXCEEDED429Your plan's daily minutes are used up (data.bound is agent_daily_minutes), or too many session requests from one key.Wait for Retry-After.Yes
BILLING_AUTHORIZATION_UNAVAILABLE, SERVER_DEPENDENCY_FAILURE503Billing or another dependency is briefly unavailable.Back off and retry with the same Idempotency-Key.Yes

A session request is checked in this order, and the first failure is returned: key (401), agent scope (403), body size (413), body (400), account access (403 AUTH_FORBIDDEN), credit (402), concurrent calls (429), daily minutes (429).

Calls that end after they started report an end reason instead of an error code.

Socket.IO-only codes and route-shared model errors

CodeHTTPCauseWhat to doRetry
RATE_LIMIT_SERVICE_BUSYSocket.IO onlyThe service is busy.Back off and follow retryable.—
TTS_MODEL_NOT_FOUND400The TTS model isn't available on this deployment, or the model value is stale (the Socket.IO surface and POST /v1/audio/speech share this code).Set model to a deployed key (nebula).After a change
TTS_VOICE_LIST_FAILEDSocket.IO onlyThe voice list could not be loaded.Request the list again later.—

SERVER_INTERNAL and RATE_LIMIT_EXCEEDED can also arrive as Socket.IO events.

Retrying safely

Retry only when retryable is true, the operation is safe to repeat, and your deadline allows it. Bound attempts, each delay and total retry time, and add jitter.

  • Wait time. Honour Retry-After or retry_after_seconds when present. Otherwise use capped exponential backoff; batch 429 has no guaranteed Retry-After.
  • Realtime and TTS 429. These rejections consume no credit or quota.
  • Batch capacity. data.capacity on batch 429 is remaining audio seconds; 0 can mean no balance was available. Use it to pace submissions, not as a sleep time.
  • Batch submissions. There is no idempotency key, so after a timeout or 500 a job may exist. See Batch REST.
  • Batch result reads. Pass save_result=true so a lost response doesn't clear the result. See Batch REST.
  • Streams. There is no resume or frame replay. Stop sending, keep committed results, discard provisional ones, and reconnect with a fresh UUID.
  • Billing errors mid-stream are terminal: the server sends the error, then disconnects. Audio accepted before it is billed.

This example retries a batch result read up to five times with backoff and jitter:

batch-error-retry.ts
import {
  BatchTranscribeClient,
  BatchTranscribeError,
  BatchTranscribeRateLimitError,
  Language,
  type TranscriptionResponse,
} from '@humain-voice/sdk';

function requiredEnv(name: 'API_KEY' | 'API_URL'): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

async function pause(milliseconds: number): Promise<void> {
  await new Promise<void>((resolve) => setTimeout(resolve, milliseconds));
}

async function getResultWithRetry(
  client: BatchTranscribeClient,
  jobId: string,
  attempts = 5,
): Promise<TranscriptionResponse> {
  for (let attempt = 1; attempt <= attempts; attempt += 1) {
    try {
      // saveResult keeps the stored result readable for a retry.
      return await client.getResult(jobId, Language.ArEn, { saveResult: true });
    } catch (error: unknown) {
      let retryable: boolean;
      let serverDelayMs = 0;
      if (error instanceof BatchTranscribeError) {
        retryable = error instanceof BatchTranscribeRateLimitError || error.retryable === true;
        if (error instanceof BatchTranscribeRateLimitError && error.retryAfter !== undefined) {
          serverDelayMs = error.retryAfter * 1_000;
        }
        console.error('error:', error.code ?? '', error.statusCode ?? '', error.capacity ?? '');
      } else if (error instanceof TypeError) {
        // fetch reports network failures as TypeError; a result read is safe to retry.
        retryable = true;
        console.error('error:', 'network', error.message);
      } else {
        throw error;
      }
      if (!retryable || attempt === attempts) throw error;

      const exponentialDelayMs = 500 * 2 ** (attempt - 1);
      await pause(Math.max(serverDelayMs, exponentialDelayMs) + Math.random() * 250);
    }
  }

  throw new Error('Retry loop exhausted');
}

async function main(): Promise<void> {
  const jobId = process.argv[2];
  if (!jobId) throw new Error('Pass a batch job ID as the first argument');

  const client = new BatchTranscribeClient({
    api_url: requiredEnv('API_URL'),
    api_key: requiredEnv('API_KEY'),
    api_version: process.env.API_VERSION ?? 'v1',
  });
  try {
    const result = await getResultWithRetry(client, jobId);
    console.info('status:', result.status);
    console.info(result.results?.transcript ?? '');
  } finally {
    await client.close();
  }
}

void main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

Pass a job ID as the first argument. Expected output (illustrative):

error: SERVER_INTERNAL 500
status: done
Hello and welcome to the meeting.

Timeouts

Set a timeout on each request and an overall deadline on the workflow. A request timeout means your client stopped waiting, not that the server stopped. The overall deadline covers connection, work, retries and cleanup; when it expires, stop.

The server has its own deadlines: TTS synthesis ends after 25 s overall or 60 s without progress, and an HTTP session ends after 900 s idle. After the first audio block reaches inference, an unfinished ASR stream also expires after 60 s without another forwarded audio block. Inference responses do not reset that timer. An HTTP streaming response that closes after about 2 s is normal and keeps the session.

Clean up in finally. Disconnecting a TTS Socket.IO connection cancels that connection's in-flight requests, and the server sends no further audio or errors for them. Aborting an HTTP TTS request cancels its synthesis. SDK timeout defaults are on the JavaScript and Python SDK pages.

On this page