API Responses

Success Responses

Successful API calls return a 200 OK status code with a simple response format:

{
  "success": true
}

All successful responses include a success: true flag.

Error Responses

When an error occurs, the API returns an appropriate HTTP status code and a simple error response:

{
  "success": false,
  "message": "The provided API key is invalid."
}

Error responses include a success: false flag and a message describing the error.

Common Error Types

Authentication Errors
Rate Limit Errors
Validation Errors

{
  "success": false,
  "message": "The provided API key is invalid."
}

HTTP Status: 401 Unauthorized

{
  "success": false,
  "message": "Too many requests. Please try again in 60 seconds."
}

HTTP Status: 429 Too Many Requests

{
  "success": false,
  "message": "Invalid parameters provided."
}

HTTP Status: 400 Bad Request

Error Handling

Here’s how to handle common errors in your application:

SDK Error Handling
REST API Error Handling

try {
  const result = await suonora.audio.speech({
    input: "Hello, world!",
    voice: "axel"
  });

  if (!result.success) {
    console.error(result.message);
    return;
  }

  // Handle successful response
  console.log('Speech generated successfully');

} catch (error) {
  if (error.status === 429) {
    console.error('Rate limited. Please try again later.');
  } else if (error.status === 401) {
    console.error('Authentication failed. Check your API key.');
  } else {
    console.error('Request failed:', error.message);
  }
}

async function generateSpeech() {
  try {
    const response = await fetch("https://api.suonora.com/v1/audio/speech", {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${API_KEY}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        input: "Hello, world!",
        voice: "axel"
      })
    });

    const data = await response.json();

    if (!data.success) {
      console.error(data.message);
      return;
    }

    // Handle successful response
    console.log('Speech generated successfully');

  } catch (error) {
    if (error.status === 429) {
      console.error('Rate limited. Please try again later.');
    } else if (error.status === 401) {
      console.error('Authentication failed. Check your API key.');
    } else {
      console.error('Request failed:', error.message);
    }
  }
}

Always implement proper error handling in your application to gracefully handle API errors and provide a good user experience.

Best Practices

Implement Retry Logic
- Use exponential backoff for rate limit errors
- Respect the Retry-After header
- Set reasonable retry limits
Handle Authentication
- Store API keys securely
- Rotate keys regularly
- Monitor for unauthorized access
Validate Input
- Check parameters before sending
- Handle validation errors gracefully
- Provide clear error messages to users
Monitor Usage
- Track API call success rates
- Monitor rate limit usage
- Set up alerts for unusual patterns

For production applications, consider implementing a robust error handling system that includes logging, monitoring, and alerting.

Get Started

Essentials

Best Practices

​Best Practices

Best Practices