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.
| Field | HTTP | Socket.IO | Meaning |
|---|---|---|---|
code | Yes | Yes | Machine-readable error code. |
retryable | Yes | Yes | Whether a retry of this request can succeed. |
timestamp | Yes | Yes | Server time of the error. |
data | Yes | Yes | On limit rejections: limit, observed, unit, bound. Batch 429 carries { capacity } instead. |
error, detail | Yes | No | Legacy identifier and human-readable text. |
message | 401 missing key only | Yes (always) | Human-readable text. |
job_id / id | job_id | id | Job or stream UUID. |
request_id | Batch | No | Trace ID for support requests. |
retry_after_seconds | No (Retry-After header) | Yes | Seconds to wait before retrying. |
reason, retry_scope | No | ASR_STREAM_EXPIRED only | Why 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
| Limit | Value | When exceeded | data.bound |
|---|---|---|---|
| Request size, including multipart overhead | 512 MiB | 413 PAYLOAD_TOO_LARGE | request_bytes |
| Audio files per request | 1 | 422 FILE_COUNT_EXCEEDED | file_parts |
| Multipart parts per request | 8 | 422 FILE_COUNT_EXCEEDED | multipart_parts |
| Decoded audio duration | 4 h (14,400 s) | 422 AUDIO_DURATION_EXCEEDED | audio_duration |
| Diarization processing duration, all models | 2,097 s (34 min 57 s), with a 64 MiB decoded-audio cap | Worker rejects processing after job creation | None |
| Audio capacity | In audio seconds | 429 RATE_LIMIT_EXCEEDED | None; 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
| Limit | Value | When exceeded | data.bound |
|---|---|---|---|
| Upload size | 64 MiB | HTTP 413 PAYLOAD_TOO_LARGE. Socket.IO emits the error, then disconnects. | fast_audio_bytes |
| Decoded audio duration | 1800 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
| Limit | Value | When exceeded | data.bound |
|---|---|---|---|
| Frame size, including the 18-byte header | 16 MiB per event or POST | 413 PAYLOAD_TOO_LARGE. Socket.IO emits the error, then disconnects. | realtime_asr_frame_bytes |
| HTTP session idle time | 900 s | 408 SESSION_IDLE_TIMEOUT | session_idle |
| Concurrent streams | Per account, set by your plan | 429 CONCURRENCY_LIMIT_EXCEEDED | account_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
| Limit | Value | When exceeded | data.bound |
|---|---|---|---|
| Frame size, including the header | 16 MiB | 413 PAYLOAD_TOO_LARGE | realtime_diarization_frame_bytes |
| HTTP POSTs in flight | 1 per stream UUID | Records can reach the wrong response | None |
Text to speech
| Limit | Value | When exceeded | data.bound |
|---|---|---|---|
text length | 500 code points (free), 1,000 (standard and enterprise) | 422 CHARACTER_COUNT_EXCEEDED | tts_input_characters |
| Voice references | 1 | 422 VOICE_REFERENCE_COUNT_EXCEEDED | tts_voice_reference_count |
| Reference transcript | 500 code points | 422 CHARACTER_COUNT_EXCEEDED | tts_voice_reference_text_characters |
| Reference audio size, decoded | 2 MiB | 413 PAYLOAD_TOO_LARGE | tts_voice_reference_bytes |
| Reference audio duration | 15 s | 422 AUDIO_DURATION_EXCEEDED | tts_voice_reference_duration |
| HTTP request body | 16 MiB | 413 PAYLOAD_TOO_LARGE | None |
| Synthesis time | 25 s overall | 504 TTS_DEADLINE_EXCEEDED | None |
| Concurrent syntheses | Per account, set by your plan | 429 CONCURRENCY_LIMIT_EXCEEDED | account_concurrency_tts |
Code points are Unicode code points, including leading and trailing whitespace. TTS limits are checked before any charge.
Voice agent
| Limit | Value | When exceeded | data.bound |
|---|---|---|---|
| Session request body | Set by HUMAIN Voice; see data.limit | 413 PAYLOAD_TOO_LARGE | agent_request_bytes |
| Client tools per session | 16 | 400 VALIDATION_INVALID_PARAM | agent_client_tools |
| Time to join after the request | About 60 s (expires_at) | The call ends as user_never_joined | None |
| Client tool result | 15 KiB of JSON | The tool call fails | None |
| Client tool run time | 120 s | The tool call fails | None |
| Concurrent calls | Per account, set by your plan | 429 CONCURRENCY_LIMIT_EXCEEDED | account_concurrency_agent |
| Daily minutes | Per account, set by your plan; resets at 00:00 UTC | 429 RATE_LIMIT_EXCEEDED | agent_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:
| Retry | Meaning |
|---|---|
| Yes | Safe to retry the same request after a backoff. |
| After a change | Fix the input, key or plan first. |
| New stream | Start a fresh stream or session with a new UUID. |
| Not automatically | An earlier attempt may have succeeded. |
| — | Not documented; follow retryable in the error. |
Common codes
| Code | HTTP | Cause | What to do | Retry |
|---|---|---|---|---|
AUTH_UNAUTHORIZED | 401 | Missing or invalid API key. | Send a valid x-api-key. | After a change |
AUTH_FORBIDDEN | 403 | Key lacks this capability. | Use a key with the capability. | After a change |
METHOD_NOT_ALLOWED | 405 | Wrong HTTP method, or the obsolete speaker_id event. | Fix the route or event. | After a change |
VALIDATION_INVALID_FORMAT | 400 | Malformed body, frame or reference WAV. | Fix the encoding. | After a change |
VALIDATION_REQUIRED_FIELD | 400 | Missing field, empty text or missing start bit. | Add the field. | After a change |
VALIDATION_INVALID_PARAM | 400 | Invalid parameter or both voice selectors. | Fix the parameter. | After a change |
VALIDATION_INVALID_UUID | 400 | Malformed job ID or voice_id. | Send a valid UUID. | After a change |
VALIDATION_INVALID_LANGUAGE | 400 | Unknown language. | Use a listed language. | After a change |
VALIDATION_FILE_CORRUPT | 400; 422 batch | Corrupt or empty audio, or a short frame. | Send valid audio. | After a change |
ASR_MODEL_NOT_FOUND | 400 | Batch or fast model not available. | Choose a listed model. | After a change |
PAYLOAD_TOO_LARGE | 413 | Over a byte limit (data.bound). | Send smaller files or frames. | After a change |
AUDIO_DURATION_EXCEEDED | 422 | Over a duration limit (data.bound). | Split the audio. | After a change |
CREDITS_EXHAUSTED | 402 | Account out of credit. | Stop and add credit. | After a change |
BILLING_AUTHORIZATION_UNAVAILABLE | 503 | Billing couldn't authorize. | Back off and retry. | Yes |
RATE_LIMIT_EXCEEDED | 429 | Batch capacity or per-key request rate; the gateway body may not be an ErrorResponse. | Slow down and back off. | Yes |
CONCURRENCY_LIMIT_EXCEEDED | 429 | Too many operations in flight. | Wait for Retry-After / retry_after_seconds. | Yes |
SERVER_INTERNAL | 500 | Unexpected 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
| Code | HTTP | Cause | What to do | Retry |
|---|---|---|---|---|
FILE_COUNT_EXCEEDED | 422 | Too many files or parts. | Send one file. | After a change |
TRANSCRIPTION_JOB_NOT_FOUND | 404 | No job with that UUID. | Stop polling; check the stored ID. | After a change |
ASR_TRANSCRIPTION_FAILED | 500 | Submission failed. | A job may exist; don't resubmit without a duplicate policy. See Batch REST. | Not automatically |
Fast, realtime and diarization codes
| Code | HTTP | Cause | What to do | Retry |
|---|---|---|---|---|
ASR_UNSUPPORTED_CODEC | 400 | Fast audio isn't AAC, FLAC, MP3, WAV or MP4. | Re-encode the file. | After a change |
ASR_TRANSCRIPTION_FAILED | 500 | Recognition failed. | Start a new stream. | New stream |
ASR_STREAM_EXPIRED | none | No audio within the idle window, or the server lost the stream state (see reason). | Start a new stream. | New stream |
SESSION_BYTE_RATE_EXCEEDED | 429 | Audio arrives faster than the session rate. | Wait, then resend the same payload (direct API; the SDKs end the stream). | Yes |
SESSION_SLOTS_EXHAUSTED | 429 | Too many open HTTP sessions. | Finish sessions, then retry. | Yes |
SESSION_BYTES_EXCEEDED | 413 | Session sent too many bytes; limit in data.limit. | Start a new session. | New stream |
SESSION_DURATION_EXCEEDED | 422 | Session open too long; limit in data.limit. | Start a new session. | New stream |
SESSION_IDLE_TIMEOUT | 408 | No audio within the idle window. | Start a new session. | New stream |
SESSION_EXPIRED | 409 | UUID not started, ended, or started twice. | Start a new session. | New stream |
DIARIZATION_MODEL_NOT_FOUND | 400 | Diarization not configured. | Contact support. | After a change |
DIARIZATION_FAILED | 500 | Capacity or inference failure. | Start a new stream. | New stream |
Text-to-speech codes
| Code | HTTP | Cause | What to do | Retry |
|---|---|---|---|---|
CHARACTER_COUNT_EXCEEDED | 422 | Text or reference transcript too long. | Shorten to data.limit. | After a change |
VOICE_REFERENCE_COUNT_EXCEEDED | 422 | More than one reference. | Send one. | After a change |
TTS_VOICE_NOT_FOUND | 400 | voice_id isn't available. | Pick from the voice list. | After a change |
TTS_INPUT_NOT_ALLOWED | 400 | Content policy rejected the text. | Change the text. | After a change |
TTS_MODERATION_UNAVAILABLE | 503 | Moderation couldn't decide. | Back off and retry. | Yes |
TTS_EMOTION_MARKUP_INVALID | 400 | A 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_EXCEEDED | 400 | Tags 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_SHORT | 400 | A 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_FAILURE | 503 | Storage outage resolving voice_id. | Back off and retry. | Yes |
TTS_VOICE_RESOLUTION_FAILED | 500 | Stored voice data is broken. | Choose another voice. | After a change |
TTS_SYNTHESIS_FAILED | 500 | Model or capacity failure. | Retry with a fresh UUID. | Yes |
TTS_DEADLINE_EXCEEDED | 504 | Synthesis exceeded 25 s. | Discard partial audio and retry. | Yes |
BILLING_IDEMPOTENCY_CONFLICT | 409 | The 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
| Code | HTTP | Cause | What to do | Retry |
|---|---|---|---|---|
VALIDATION_INVALID_PARAM | 400 | Unknown 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_MISSING | 403 | The key lacks the agent scope; data.required_scope is agent. | Enable the agent scope on the key in the console. | After a change |
AUTH_FORBIDDEN | 403 | Voice Agent isn't enabled for the account during the beta, or is turned off. | Contact support. | After a change |
AGENT_SESSION_NOT_FOUND | 404 | GET /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_EXHAUSTED | 402 | No credit for the first minute, or the account isn't on credit billing. | Add credit, or contact support. | After a change |
CONCURRENCY_LIMIT_EXCEEDED | 429 | Your 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_EXCEEDED | 429 | Your 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_FAILURE | 503 | Billing 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
| Code | HTTP | Cause | What to do | Retry |
|---|---|---|---|---|
RATE_LIMIT_SERVICE_BUSY | Socket.IO only | The service is busy. | Back off and follow retryable. | — |
TTS_MODEL_NOT_FOUND | 400 | The 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_FAILED | Socket.IO only | The 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-Afterorretry_after_secondswhen present. Otherwise use capped exponential backoff; batch429has no guaranteedRetry-After. - Realtime and TTS
429. These rejections consume no credit or quota. - Batch capacity.
data.capacityon batch429is remaining audio seconds;0can 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
500a job may exist. See Batch REST. - Batch result reads. Pass
save_result=trueso 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:
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.