Metadata

name: gladia-troubleshooting
description: Diagnose and fix common Gladia API issues. Use when the user encounters errors (401, 403, 429), unexpected behavior, poor transcription quality, billing confusion, audio format problems, WebSocket disconnections, polling failures, or asks about limits and rate limiting. SDK-first diagnostics — many issues are solved by migrating to the official SDK.
license: MIT

Troubleshooting

Common issues, gotchas, and their solutions when working with the Gladia API.

SDK-first diagnostics: first verify the user is on the official SDK — many issues (polling, reconnection, retries) are solved automatically. See gladia-sdk-integration for setup and policy.

When to Use

User encounters errors (401, 403, 429, invalid format, timeout) when calling the Gladia API
Unexpected behavior: poor transcription quality, missing words, wrong language
WebSocket disconnections, polling failures, or session hangs
Billing confusion (multi-channel, concurrency limits, plan restrictions)
Verifying that an integration is correctly configured before going to production

When NOT to use: For initial SDK setup and configuration, use gladia-sdk-integration. For feature-specific guidance (options, parameters, response structure), use gladia-pre-recorded-transcription or gladia-live-transcription.

References

Consult these resources as needed:

../gladia-sdk-integration/SKILL.md -- SDK setup, client config (retry, timeouts), and SDK vs raw API decision guide
../gladia-sdk-integration/references/sdk-versions.md -- Current SDK versions (auto-synced by CI)
../gladia-pre-recorded-transcription/SKILL.md -- Pre-recorded config options and limits
../gladia-live-transcription/SKILL.md -- Live session config and WebSocket event handling
../gladia-audio-intelligence/SKILL.md -- Audio intelligence feature configs and availability matrix

Authentication Errors

401 Unauthorized

Cause: Invalid or missing API key
Fix (SDK): Verify the key is passed via the apiKey (JS) / api_key (Python) constructor option, or set the GLADIA_API_KEY environment variable
Fix (raw REST): Verify the key is passed in the x-gladia-key header
Check: Go to app.gladia.io → API keys → verify the key is active

403 Forbidden

Cause: Key doesn't have access to the requested feature or region
Fix: Check your plan tier; some features are plan-restricted

Rate Limiting and Concurrency

429 Too Many Requests

Concurrency limits by plan:

Plan	Pre-recorded	Live	Notes
Free	3	1	10 hrs/month total
Starter	25	30	—
Growth	25	30	—
Enterprise	Unlimited	Unlimited	—

Fix: Wait for in-progress jobs to complete before starting new ones, or upgrade your plan.

Common Gotchas

1. Code switching without language list

Problem: Enabling code_switching: true with an empty languages array causes evaluation across 100+ languages and frequent misdetections.

Fix: Always provide 3-5 expected languages:

{
  "language_config": {
    "languages": ["en", "fr", "es"],
    "code_switching": true
  }
}

2. Custom vocabulary intensity too high

Problem: intensity values above 0.6 cause false positives where unrelated words get replaced by vocabulary entries.

Fix: Keep intensity at 0.4-0.6. Use pronunciations for better recognition instead of raising intensity:

{
  "vocabulary": [
    { "value": "Gladia", "pronunciations": ["gla-dee-ah"], "intensity": 0.5 }
  ]
}

3. Audio exceeding duration limits silently

Problem: Pre-recorded files over 135 minutes may fail without a clear error message.

Fix: Split long audio into chunks of ~60 minutes before uploading. For enterprise (4h15 limit), contact support.

4. Multi-channel billing surprise

Problem: Sending 2-channel (stereo) audio is billed as 2x the duration.

Fix: Merge to mono if you don't need per-channel speaker identification. Only use multi-channel intentionally for distinct audio sources.

5. WebSocket disconnection without recovery

Problem: If the WebSocket drops, creating a new session loses context.

Fix (SDK — recommended): The SDK handles reconnection automatically with configurable wsRetry. No action needed if using the SDK.

Fix (raw WebSocket): Reconnect to the same WebSocket URL to resume the session. Do NOT call /v2/live again.

6. Polling without backoff

Problem: Rapidly polling /v2/pre-recorded/:id wastes requests and may trigger rate limits.

Fix (SDK — recommended): The SDK handles polling automatically. Use transcribe() which includes built-in backoff, or configure poll() directly:

const result = await client.preRecorded().transcribe(audio, options, {
  interval: 5000, // 5 seconds between polls
});

result = client.prerecorded().transcribe(
    "audio.mp3",
    options,
    {"interval": 5000},  # 5 seconds between polls
)

Fix (raw REST): Implement exponential backoff (start at 3s, max 30s), or use webhooks/callbacks instead.

7. Forgetting to stop recording

Problem: Leaving a WebSocket open without sending stop_recording keeps the session hanging until the 3-hour timeout.

Fix: Always explicitly call session.stopRecording() (or session.stop_recording() in Python) when done. Implement cleanup in error handlers.

8. Partial transcripts not appearing

Problem: Real-time results come only as final transcripts by default.

Fix: Enable partial transcripts in session config:

{
  "messages_config": {
    "receive_partial_transcripts": true
  }
}

9. Expecting diarization in live mode

Problem: Speaker diarization is only available for pre-recorded transcription.

Fix: For live multi-speaker scenarios, use multi-channel audio with one speaker per channel and track by channel number.

10. PII redaction in live mode

Problem: pii_redaction: true is silently ignored in live transcription.

Fix: PII redaction only works for pre-recorded. For live compliance needs, implement client-side redaction on the transcript text.

Audio Format Issues

"Invalid audio format" error

Verify encoding, sample_rate, bit_depth, channels match your actual audio stream
For pre-recorded: format is auto-detected from the file; this error is live-specific
For supported formats and size limits, see gladia-pre-recorded-transcription and gladia-live-transcription

Transcription Quality Issues

Poor accuracy

Check audio quality: Background noise, low volume, or heavy compression degrades results
Enable audio enhancer: pre_processing.audio_enhancer: true (live)
Specify languages: Always provide expected languages rather than relying on auto-detection
Use custom vocabulary: For domain-specific terms (medical, legal, technical)
Check sample rate: Higher sample rates (16kHz+) give better results than 8kHz

Wrong language detected

Provide explicit languages list
If multi-language, enable code_switching with 3-5 expected languages
For single-language content, specify exactly one language and disable code switching

Missing words or gaps

Check for silence or very low volume sections
Verify audio isn't corrupted (try playing it back)
For live: ensure chunks are sent continuously without large gaps

Webhook/Callback Issues

Callbacks not received

Verify callback_url is publicly reachable (not localhost)
Check your server returns 2xx within timeout
Verify no firewall/WAF blocking incoming requests
Test with a service like webhook.site first

Webhook signature verification

Webhooks are powered by Svix. Verify using the Svix libraries:

import { Webhook } from "svix";
const wh = new Webhook(webhookSecret);
wh.verify(payload, headers);

Verification Checklist

Before submitting transcription work:

Gladia Troubleshooting

安装技能