This guide covers the main types of errors that can occur during API calls and their solutions. Supertone API indicates the cause of problems through HTTP status codes, and through this document, you can check in advance what errors may occur in which situations.

​
1. Error Codes

​
400 Bad Request

This occurs when there’s a problem with the request format itself. The most common causes are:
  • Missing required fields like text, language
  • Entering non-existent values for style or model
  • voice_settings parameter values outside the allowed range (e.g., pitch_shift: 20)
  • Invalid JSON or completely wrong format
  • Text length exceeding 300 characters
Please check your request body again. Using an editor or Linter to validate JSON structure is also recommended.

​
401 Unauthorized

This occurs when the API Key is missing or incorrect.
  • Missing x-sup-api-key header
  • Using an incorrect key (different account key, expired key, etc.)
Please verify that you entered the API Key issued from the console correctly. Be careful not to include leading or trailing spaces when copying strings.

​
402 Not Enough Credits

This occurs when there aren’t enough credits remaining to process the API call.
  • Credits are 0 or insufficient for the expected call cost
  • Plan not purchased in Play/console
Purchase a plan or charge credits on the Play subscription page and try again.
Credits are also deducted when calling cloned voices.

​
403 Forbidden

This occurs when trying to access resources without permission.
  • The voice_id doesn’t belong to your account (e.g., another user’s cloned voice)
  • Sub-users of enterprise accounts trying to use resources they don’t have permission for
  • Using an API Key not issued from the console
Call GET /v1/voices to recheck permission for that voice.
Cloned voices can only be called by the account that created them.
403 occurs if the account is different.

​
404 Not Found

This occurs when the specified resource cannot be found.
  • Using a non-existent voice_id
  • When filtering with too narrow conditions in GET /voices/search results in 0 results
  • Typo in endpoint path
Please recheck that the request path and parameter values are correct.
voice_id can be verified through the console or GET /voices.

​
408 Request Timeout

This occurs when the server cannot process the request within a certain time.
  • When the network is unstable or the request body is too large and complex
  • When processing delays occur internally on the server
If the same request repeatedly times out, please contact customer support.
You can try simplifying the request or reducing input values.

​
429 Too Many Requests

This error occurs when too many requests are sent within a short period of time.
  • For more details, see the Rate Limits section.
  • Exceeding the limit may cause temporary delays or blocking of responses.
Please wait a moment before sending the request again.
If you’re an enterprise user, you may request a higher limit. (Enterprise Inquiry)

​
500 Internal Server Error

This is an unexpected internal server error.
  • It’s likely a temporary server issue
  • Can occur intermittently even when there’s no problem with the request itself
If the same request repeatedly fails, please contact customer support including the request body.
Logging the occurrence time helps with problem resolution.

​
2. Common Error Cases

  • Getting 400 by calling without sending request body
  • Getting 401 by incorrectly setting API Key in Postman environment variables
  • Getting 403 when trying to call cloned voice from different account
  • Getting 402 when calling again after using up all credits
  • Getting 400 because input text was 310 characters (exceeding 300 character limit)

​
3. Error Response Tips

  • Most errors can be immediately identified along with HTTP status codes
  • Error messages don’t include detailed descriptions, so carefully review your request content
  • For recurring errors, contact customer support including request body and header content.