Error Handling

Handle API errors correctly

All errors return a consistent JSON format with HTTP status codes.

Error response format

{
  "success": false,
  "message": "Error description"
}

Common errors

401 Unauthorized

Missing or invalid API key.

{
  "success": false,
  "message": "Authorization header is missing or invalid."
}

Fix: Include valid API key in Authorization header.

403 Forbidden

Valid API key but insufficient permissions.

{
  "success": false,
  "message": "Access denied. This API is only available for Pro and Business plans."
}

Fix: Upgrade to Pro or Business plan.

400 Bad Request

Invalid request parameters.

{
  "success": false,
  "message": "Invalid 'voice' parameter. A valid voice identifier is required."
}

Fix: Check your request parameters match the API documentation.

404 Not Found

Voice or model doesn’t exist.

{
  "success": false,
  "message": "The requested voice does not exist."
}

Fix: Use valid voice/model IDs from the lists.

413 Payload Too Large

Text exceeds 5,000 characters.

{
  "success": false,
  "message": "The provided text exceeds the 5000-character limit."
}

Fix: Split text into smaller chunks under 5,000 characters.

500 Internal Server Error

Server-side processing error.

{
  "success": false,
  "message": "Processing failed",
  "retryable": false
}

Fix: Retry the request. If it persists, contact support.

Error handling example

JavaScript

async function safeRequest(text, voice, model) {
  try {
    const response = await fetch('https://api.neospeech.io/v1/audio/speech', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ input: text, voice, model })
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message);
    }

    return await response.blob();
  } catch (error) {
    console.error('Request failed:', error.message);
    throw error;
  }
}

HTTP status codes

Code	Meaning
200	Success
400	Bad request - invalid parameters
401	Unauthorized - invalid API key
403	Forbidden - insufficient permissions
404	Not found - invalid voice/model
413	Payload too large - text > 5,000 chars
500	Server error - processing failed