​
Response Status Codes

Supertone API uses standard HTTP status codes to indicate the success or failure of API requests.

Status CodeDescription
200 - OKThe request was successfully processed.
400 - Bad RequestThe request cannot be processed. This response occurs when required parameters are missing or parameter formats are incorrect. Please check your request parameters using the error code.
401 - UnauthorizedThe provided API key is invalid.
403 - ForbiddenThe API key does not have permission for this request.
404 - Not FoundThe requested resource does not exist. Please check the requested API endpoint again.
500 - Internal Server ErrorAn error occurred on the Supertone server.

​
Error Response Format

When a request is not processed normally, an error object like the following is returned along with the HTTP status code.

{
    "status": "error",
    "message": {
        "statusCode": 400,
        "message": [
            "The text must be less than 200 characters",
            "language must be one of the following values: en, ko, ja"
        ],
        "error": "Bad Request"
    }
}

{
  "status": "error",
  "message": {
    "statusCode": 500,
    "message": "Failed to convert text to speech",
    "error": "Internal Server Error"
  }
}

​
Troubleshooting Guide

​
1. API Key Issues (401, 403)

Symptoms

  • 401 Unauthorized error
  • 403 Forbidden error
  • “Invalid API key” message
{
    "status": "error",
    "message": {
        "statusCode": 401,
        "message": "Invalid API key",
        "error": "Unauthorized"
    }
}

Checklist

  1. API Key Inclusion
    • Verify that the API key is included in the header of all requests
    • Confirm that the header name is exactly x-sup-api-key
  2. API Key Format
    • Check that the API key doesn’t contain any extra spaces
    • Verify that the API key was copied completely
  3. API Key Validity
    • Check the API key status in the console
    • Verify that the API key hasn’t expired
    • Confirm that the API key hasn’t been revoked

Solutions

  • Generate a new API key from the console
  • Update API key values in environment variables or configuration files
  • Recheck API key permissions

​
2. Bad Request Issues (400)

Symptoms

  • 400 Bad Request error
  • Parameter-related error messages
  • Request format error messages
{
    "status": "error",
    "message": {
        "statusCode": 400,
        "message": [
            "language must be one of the following values: en, ko, ja"
        ],
        "error": "Bad Request"
    }
}

{
    "status": "error",
    "message": {
        "statusCode": 400,
        "message": [
            "The text must be less than 200 characters"
        ],
        "error": "Bad Request"
    }
}

Checklist

  1. Required Parameters
    • Verify that all required parameters are included
    • Check that parameter names are correct
  2. Parameter Format
    • Verify that text length does not exceed 200 characters
    • Check that JSON format is correct
    • Confirm that parameter value data types are correct
  3. Encoding
    • Verify that text encoding is UTF-8
    • Check that special characters are properly encoded

Solutions

  • Review parameter specifications in the API documentation
  • Validate JSON format in the request body
  • Adjust text length and encoding

​
3. Resource Access Issues (404, 500)

Symptoms

  • 404 Not Found error
  • 500 Internal Server Error
  • “Resource not found” message

Checklist

  1. API Endpoint
    • Verify that the URL is correct (https://supertoneapi.com/v1/...)
    • Check that the API version is correct
  2. Voice ID
    • Check available voice list through Get Voices API
    • Verify case sensitivity of the voice ID
  3. Access Permissions
    • Confirm access permissions for the voice
    • Check subscription status
{
    "status": "error",
    "message": {
        "statusCode": 500,
        "message": "An error occurred while fetching the voice",
        "error": "Internal Server Error"
    }
}

Solutions

  1. Check the latest voice list through Get Voices API
  2. Reconfirm API endpoint address
  3. Verify voice access permissions

​
4. Server Errors (500)

Symptoms

  • 500 Internal Server Error
  • Server response timeout
  • Unexpected error messages

Checklist

  1. Server Status
    • Check service status page
    • Verify if it’s a temporary server issue
  2. Request Frequency
    • Check if request limits have been exceeded
    • Verify number of concurrent requests
  3. Network Status
    • Check network connection status
    • Verify firewall settings

Solutions

  • Try again after a short wait
  • Adjust request intervals
  • Contact technical support if problems persist

​
Error Technical Support

If you have difficulty resolving an issue or if it persists, please contact our technical support team with the following information:

  • Email: techsupport@supertone.ai
  • Required Information:
    • Last 4 digits of your API key (visible in the console page)
    • Time when the error occurred
    • Requested API endpoint
    • Complete error message
    • Steps to reproduce
    • Request/response examples (excluding sensitive information)
Text-to-speech GuidePricing