Error Handling

The Uberduck API uses standard HTTP status codes to indicate the success or failure of API requests. In addition to the status code, error responses include a JSON object with detailed information about what went wrong.

Error Response Format

All API errors return a JSON object with the following structure:

{
  "error": {
    "code": "error_code",
    "message": "A human-readable error message",
    "details": {
      // Additional information about the error (optional)
    }
  }
}

HTTP Status Codes

Status Code	Description
200	OK - The request was successful.
400	Bad Request - The request was invalid or cannot be served.
401	Unauthorized - Authentication is required or failed.
403	Forbidden - The authenticated user doesn't have permission.
404	Not Found - The requested resource doesn't exist.
422	Unprocessable Entity - The request was well-formed but contains semantic errors.
429	Too Many Requests - Rate limit exceeded.
500	Internal Server Error - Something went wrong on our end.
503	Service Unavailable - The service is temporarily unavailable.

Common Error Codes

Authentication Errors

Error Code	Description
missing_api_key	No API key was provided.
invalid_api_key	The provided API key is invalid.
expired_api_key	The provided API key has expired.
insufficient_permissions	The API key doesn't have permission for the requested operation.

Request Errors

Error Code	Description
invalid_request	The request contains invalid parameters.
missing_required_parameter	A required parameter is missing.
invalid_parameter_value	A parameter has an invalid value.
unsupported_parameter	An unsupported parameter was provided.

Resource Errors

Error Code	Description
voice_not_found	The specified voice doesn't exist.
model_not_found	The specified model doesn't exist.
voice_model_incompatible	The specified voice is not compatible with the specified model.
resource_not_found	The requested resource doesn't exist.

Rate Limiting Errors

Error Code	Description
rate_limit_exceeded	You've exceeded your rate limit.
quota_exceeded	You've exceeded your quota for the current billing period.

Text-to-Speech Specific Errors

Error Code	Description
text_too_long	The provided text exceeds the maximum length.
text_empty	The provided text is empty.
unsupported_language	The language is not supported by the specified voice.
tts_failed	Text-to-speech processing failed.

Error Handling Example

// JavaScript example
async function generateSpeech(text, voice, model) {
  try {
    const response = await fetch('https://api.uberduck.ai/v1/text-to-speech', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        text,
        voice,
        model
      })
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`API error: ${errorData.error.code} - ${errorData.error.message}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('Speech generation failed:', error);
    throw error;
  }
}

Best Practices for Error Handling

1. Always check HTTP status codes - The HTTP status code will give you a high-level indication of what went wrong.

2. Parse the error response - The error response contains detailed information about what went wrong.

3. Implement exponential backoff - When you encounter rate limiting errors (429), implement exponential backoff to retry the request.

4. Log error details - Log the error code, message, and details for debugging.

5. Handle specific errors appropriately - Different errors may require different handling strategies:

   • For text_too_long errors, you might want to split the text into smaller chunks.
   • For rate_limit_exceeded errors, you should wait before retrying.
   • For voice_not_found errors, you might want to suggest alternative voices.