​
응답 상태 코드

수퍼톤 API는 표준 HTTP 상태 코드를 사용하여 API 요청의 성공 또는 실패를 나타냅니다.

상태 코드설명
200 - OK요청이 성공적으로 처리되었습니다.
400 - Bad Request요청을 처리할 수 없습니다. 필수 파라미터를 보내지 않았거나, 파라미터 포맷이 잘못되었을 때 돌아오는 응답입니다. 에러 코드를 참고하여 요청 파라미터를 확인해주세요.
401 - Unauthorized요청한 API key가 유효하지 않습니다.
403 - ForbiddenAPI Key가 해당 요청을 할 권한이 없습니다.
404 - Not Found요청한 리소스가 존재하지 않습니다. 요청한 API 주소를 다시 한 번 확인해주세요.
500 - Internal Server Error수퍼톤 서버에서 에러가 발생했습니다.

​
오류 응답 형식

요청이 정상적으로 처리되지 않으면 응답으로 HTTP 상태 코드와 함께 아래와 같은 에러 객체가 돌아옵니다.

{
    "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"
  }
}

​
트러블슈팅 가이드

​
1. API 키 관련 문제 (401, 403)

증상

  • 401 Unauthorized 오류
  • 403 Forbidden 오류
  • “Invalid API key” 메시지
{
    "status": "error",
    "message": {
        "statusCode": 401,
        "message": "Invalid API key",
        "error": "Unauthorized"
    }
}

확인사항

  1. API 키 포함 여부
    • 모든 요청의 헤더에 API 키가 포함되어 있는지 확인
    • 헤더 이름이 정확히 x-sup-api-key인지 확인
  2. API 키 형식
    • API 키에 추가 공백이 포함되어 있지 않은지 확인
    • API 키가 온전히 복사되었는지 확인
  3. API 키 유효성
    • 콘솔에서 API 키의 상태 확인
    • API 키가 만료되지 않았는지 확인
    • API 키가 폐기되지 않았는지 확인

해결 방안

  • 콘솔에서 새로운 API 키 발급
  • 환경 변수나 설정 파일의 API 키 값 갱신
  • API 키 관련 권한 재확인

​
2. 잘못된 요청 문제 (400)

증상

  • 400 Bad Request 오류
  • 파라미터 관련 오류 메시지
  • 요청 형식 오류 메시지
{
    "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"
    }
}

확인사항

  1. 필수 파라미터
    • 모든 필수 파라미터가 포함되어 있는지 확인
    • 파라미터 이름이 정확한지 확인
  2. 파라미터 형식
    • 텍스트 길이가 200자를 초과하지 않았는지 확인
    • JSON 형식이 올바른지 확인
    • 파라미터 값의 데이터 타입이 올바른지 확인
  3. 인코딩
    • 텍스트 인코딩이 UTF-8인지 확인
    • 특수문자가 올바르게 인코딩되었는지 확인

해결 방안

  • API 문서의 파라미터 스펙 재확인
  • 요청 본문의 JSON 형식 검증
  • 텍스트 길이 및 인코딩 조정

​
3. 리소스 접근 문제 (404, 500)

증상

  • 404 Not Found 오류
  • 500 Internal Server Error 오류
  • “Resource not found” 메시지

확인사항

  1. API 엔드포인트
    • URL이 정확한지 확인 (https://supertoneapi.com/v1/...)
    • API 버전이 올바른지 확인
  2. 보이스 ID
    • Get Voices API를 통해 사용 가능한 보이스 목록 확인
    • 보이스 ID의 대소문자가 정확한지 확인
  3. 접근 권한
    • 해당 보이스에 대한 접근 권한이 있는지 확인
    • 구독 상태 확인
{
    "status": "error",
    "message": {
        "statusCode": 500,
        "message": "An error occurred while fetching the voice",
        "error": "Internal Server Error"
    }
}

해결 방안

  1. Get Voices API를 통해 최신 보이스 목록 조회
  2. API 엔드포인트 주소 재확인
  3. 보이스 접근 권한 확인

​
4. 서버 오류 (500)

증상

  • 500 Internal Server Error
  • 서버 응답 시간 초과
  • 예기치 않은 오류 메시지

확인사항

  1. 서버 상태
    • 서비스 상태 페이지 확인
    • 임시적인 서버 문제인지 확인
  2. 요청 빈도
    • 요청 한도 초과 여부 확인
    • 동시 요청 수 확인
  3. 네트워크 상태
    • 네트워크 연결 상태 확인
    • 방화벽 설정 확인

해결 방안

  • 잠시 후 다시 시도
  • 요청 간격 조정
  • 지속적인 문제 발생 시 기술지원팀 문의

​
오류 기술지원 문의

문제 해결이 어렵거나 문제가 지속될 경우 아래 정보와 함께 기술지원팀으로 문의해 주시기 바랍니다.

  • 이메일: techsupport@supertone.ai
  • 필수 포함 정보:
    • API 키의 마지막 4자리(콘솔 페이지에서 확인 가능)
    • 오류 발생 시간
    • 요청한 API 엔드포인트
    • 전체 오류 메시지
    • 재현 과정
    • 요청/응답 예시 (민감한 정보 제외)
Text-to-speech 가이드요금제