Bad Request

What this error means

Root causes

How to fix it

1. 1

   Inspect the full error response body from ElevenLabs

   ElevenLabs 400 responses include a JSON body with a 'detail' field that specifies exactly what is wrong with the request. Log and inspect this response body — it often names the specific field or constraint that was violated, which makes diagnosis straightforward.

2. 2

   Validate required fields before sending the request

   Ensure all required fields for the TTS endpoint are present and non-empty before making the API call. For the /v1/text-to-speech endpoint, the required fields are: voice_id (in the URL path) and text (in the request body).

   async function synthesizeSpeech(voiceId, text, modelId = 'eleven_multilingual_v2') {
     // Validate inputs before calling the API
     if (!voiceId || typeof voiceId !== 'string') {
       throw new Error('voiceId must be a non-empty string');
     }
     if (!text || typeof text !== 'string' || text.trim().length === 0) {
       throw new Error('text must be a non-empty string');
     }
     if (!modelId || typeof modelId !== 'string') {
       throw new Error('modelId must be a non-empty string');
     }
     
     const response = await fetch(
       `https://api.elevenlabs.io/v1/text-to-speech/${voiceId}`,
       {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
           'xi-api-key': process.env.ELEVENLABS_API_KEY
         },
         body: JSON.stringify({
           text,
           model_id: modelId,
           voice_settings: { stability: 0.5, similarity_boost: 0.75 }
         })
       }
     );
     
     if (!response.ok) {
       const errorBody = await response.json().catch(() => ({}));
       throw new Error(`ElevenLabs ${response.status}: ${JSON.stringify(errorBody)}`);
     }
     
     return response.arrayBuffer();
   }

3. 3

   Verify voice_settings parameter ranges

   The voice_settings object has strict numeric range constraints. The 'stability' field must be between 0.0 and 1.0. The 'similarity_boost' field must also be between 0.0 and 1.0. Values outside these ranges will return a 400 error. Additionally, 'style' (if provided) must be between 0.0 and 1.0, and 'use_speaker_boost' must be a boolean.

4. 4

   Confirm the model_id is a currently supported model

   Use the ElevenLabs Models API to fetch the list of available models and validate your model_id against this list. Common valid model IDs include: 'eleven_monolingual_v1', 'eleven_multilingual_v1', 'eleven_multilingual_v2', 'eleven_turbo_v2', 'eleven_turbo_v2_5'. Avoid hardcoding model IDs — fetch them dynamically.

   async function getAvailableModels() {
     const response = await fetch('https://api.elevenlabs.io/v1/models', {
       headers: { 'xi-api-key': process.env.ELEVENLABS_API_KEY }
     });
     const models = await response.json();
     return models.map(m => m.model_id);
   }
   
   async function validateModelId(modelId) {
     const validModels = await getAvailableModels();
     if (!validModels.includes(modelId)) {
       throw new Error(`Invalid model_id '${modelId}'. Valid models: ${validModels.join(', ')}`);
     }
   }

5. 5

   Check Content-Type header is set correctly

   Ensure every POST request to ElevenLabs includes the 'Content-Type: application/json' header. Some HTTP client libraries require this to be set explicitly; omitting it can cause the API to reject the request with a 400 error, even if the body is valid JSON.

6. 6

   Handle empty or whitespace-only text gracefully

   ElevenLabs will return a 400 error if the text parameter is empty or contains only whitespace characters. Add a guard in your application to handle cases where the text to be synthesized is empty — either by skipping the TTS call or substituting a default phrase.

7. 7

   Log the full request payload for failed calls

   Add request logging to capture the complete body of every ElevenLabs API call alongside the response status and body. When a 400 error occurs, compare the logged request against the API documentation to identify the discrepancy quickly.

Prevention

Prevent 400 errors by building a validated request construction layer that enforces all ElevenLabs API constraints — required fields, value ranges, and correct types — before any network call is made. Use TypeScript types or a schema validation library (Zod, Joi, Yup) to model the exact shape of ElevenLabs request bodies and validate them at the boundary. Log both request and response bodies for all API calls in development and staging environments so issues are caught immediately during testing. Pin model IDs dynamically by querying the ElevenLabs Models API rather than hardcoding values that may become invalid as the API evolves.