> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suonora.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Responses

> Learn about Suonora API responses, status codes, and how to handle errors in your application.

<Steps title="Understanding API Responses">
  <Step title="Success Responses">
    Successful API calls return a `200 OK` status code with a simple response format:

    ```json
    {
      "success": true
    }
    ```

    <Note>
      All successful responses include a `success: true` flag.
    </Note>
  </Step>

  <Step title="Error Responses">
    When an error occurs, the API returns an appropriate HTTP status code and a simple error response:

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

    <Note>
      Error responses include a `success: false` flag and a `message` describing the error.
    </Note>
  </Step>

  <Step title="Common Error Types">
    <Tabs>
      <Tab title="Authentication Errors">
        ```json
        {
          "success": false,
          "message": "The provided API key is invalid."
        }
        ```

        <Note type="warning">
          HTTP Status: 401 Unauthorized
        </Note>
      </Tab>

      <Tab title="Rate Limit Errors">
        ```json
        {
          "success": false,
          "message": "Too many requests. Please try again in 60 seconds."
        }
        ```

        <Note type="warning">
          HTTP Status: 429 Too Many Requests
        </Note>
      </Tab>

      <Tab title="Validation Errors">
        ```json
        {
          "success": false,
          "message": "Invalid parameters provided."
        }
        ```

        <Note type="warning">
          HTTP Status: 400 Bad Request
        </Note>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Error Handling">
    Here's how to handle common errors in your application:

    <Tabs>
      <Tab title="SDK Error Handling">
        ```js
        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);
          }
        }
        ```
      </Tab>

      <Tab title="REST API Error Handling">
        ```js
        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);
            }
          }
        }
        ```
      </Tab>
    </Tabs>

    <Note type="info">
      Always implement proper error handling in your application to gracefully handle API errors and provide a good user experience.
    </Note>
  </Step>
</Steps>

***

## Best Practices

1. **Implement Retry Logic**

   * Use exponential backoff for rate limit errors
   * Respect the `Retry-After` header
   * Set reasonable retry limits

2. **Handle Authentication**

   * Store API keys securely
   * Rotate keys regularly
   * Monitor for unauthorized access

3. **Validate Input**

   * Check parameters before sending
   * Handle validation errors gracefully
   * Provide clear error messages to users

4. **Monitor Usage**
   * Track API call success rates
   * Monitor rate limit usage
   * Set up alerts for unusual patterns

<Note type="tip">
  For production applications, consider implementing a robust error handling
  system that includes logging, monitoring, and alerting.
</Note>