오류 처리
요청 중 발생할 수 있는 오류 유형과 그에 대한 원인 및 해결 방법을 안내합니다.
API 호출 중 발생할 수 있는 주요 오류 유형과 그에 대한 해결 방법을 안내합니다. Supertone API에서는 HTTP 상태 코드를 통해 문제의 원인을 안내하고 있으며, 이 문서를 통해 어떤 상황에서 어떤 오류가 발생할 수 있는지 미리 확인할 수 있습니다.
1. 오류 코드 목록
400 Bad Request
요청 형식 자체에 문제가 있는 경우입니다. 가장 흔한 원인은 다음과 같습니다:
text,language등 필수 필드를 누락한 경우style또는model값에 존재하지 않는 값을 입력한 경우voice_settings의 파라미터 값이 허용 범위를 벗어난 경우 (예: pitch_shift: 20)- JSON이 유효하지 않거나, 아예 잘못된 형식으로 보낸 경우
- 텍스트 길이가 300자를 초과한 경우
요청 바디를 다시 한번 확인해 주세요. 에디터나 Linter를 사용해 JSON 구조를 검증하는 것도 좋습니다.
401 Unauthorized
API Key가 누락되었거나, 올바르지 않은 경우입니다.
x-sup-api-key헤더가 없는 경우- 올바르지 않은 키를 사용하는 경우 (다른 계정 키, 만료된 키 등)
콘솔에서 발급받은 API Key를 정확히 입력했는지 확인해 주세요. 문자열 복사 시 앞뒤 공백이 포함되지 않도록 주의해야 합니다.
402 Not Enough Credits
API 호출을 처리할 수 있을 만큼의 크레딧이 남아있지 않은 경우입니다.
- 크레딧이 0이거나, 호출 예상 비용보다 부족한 경우
- Play/콘솔에서 플랜을 결제하지 않은 경우
Play 구독 페이지에서 플랜을 결제하거나, 크레딧을 충전한 뒤 다시 시도하세요.
클론드 보이스를 호출할 때도 동일하게 크레딧이 차감됩니다.
403 Forbidden
사용 권한이 없는 리소스에 접근하려고 했을 때 발생합니다.
- 해당
voice_id가 내 계정 소유가 아닐 경우 (예: 다른 사용자의 클론 보이스) - 기업 계정의 하위 사용자가 호출 권한이 없는 리소스를 사용하려는 경우
- 콘솔에서 발급되지 않은 API Key를 사용할 경우
GET /v1/voices를 호출해 해당 보이스의 이용권한 여부를 다시 확인해 보세요.
클론드 보이스는 만든 계정으로만 호출할 수 있습니다.
계정이 다를 경우 403이 발생합니다.
404 Not Found
지정한 리소스를 찾을 수 없을 때 발생합니다.
- 존재하지 않는
voice_id를 사용했을 경우 GET /voices/search에서 너무 좁은 조건으로 필터링해 결과가 0건일 때- 엔드포인트 경로 오타
요청 경로와 파라미터 값이 정확한지 다시 확인해 주세요.
voice_id는 콘솔 또는GET /voices로 확인 가능합니다.
408 Request Timeout
서버가 일정 시간 내 요청을 처리하지 못했을 때 발생합니다.
- 네트워크가 불안정하거나, 요청 바디가 너무 크고 복잡할 때
- 서버 내부적으로 처리 지연이 발생한 경우
동일한 요청이 반복적으로 Timeout되는 경우 고객 지원을 통해 문의해 주세요.
요청을 단순화하거나, 입력값을 줄여 다시 시도해볼 수 있습니다.
429 Too Many Requests
일정 시간 내 요청이 과도하게 들어온 경우입니다.
- 자세한 내용은 요청 수 제한 항목을 참조하세요.
- 이 기준을 초과하면 일시적으로 응답이 지연되거나 차단될 수 있습니다.
잠시 기다린 후 다시 요청을 보내주세요.
엔터프라이즈 사용자의 경우, 요청 제한 상향 조정이 가능합니다. (엔터프라이즈 문의하기)
500 Internal Server Error
예기치 않은 서버 내부 오류입니다.
- 일시적인 서버 문제일 가능성이 높습니다
- 요청 자체에 문제가 없더라도 간헐적으로 발생할 수 있습니다
동일한 요청이 반복적으로 실패한다면, 요청 바디를 포함하여 고객 지원을 통해 문의해 주세요.
발생 시점을 로그로 남겨두는 것이 문제 해결에 도움이 됩니다.
2. 자주 발생하는 케이스 요약
- 요청 바디를 안 보내고 호출해서 400이 남
- API Key를 Postman 환경변수로 잘못 넣어서 401 발생
- 클론드 보이스를 다른 계정에서 호출하려다 403 발생
- 크레딧을 다 쓰고 다시 호출했더니 402 발생
- 입력 텍스트가 310자여서 400이 뜸 (300자 제한 초과)
3. 오류 대응 팁
- 대부분의 오류는 HTTP 상태 코드와 함께 즉시 파악 가능합니다.
- 오류 메시지에는 자세한 설명이 포함되지 않으므로, 요청 내용을 꼼꼼히 검토해 보세요.
- 반복되는 오류는 요청 바디와 헤더 내용을 포함해 고객 지원을 통해 문의해 주세요.