에러 처리
에러 코드 레퍼런스와 문제 해결 가이드.
ListenHub API의 모든 응답은 HTTP 200 상태 코드를 사용합니다. 성공과 실패는 응답 본문의 code 필드로 구분합니다: code = 0이면 성공, code ≠ 0이면 실패입니다.
에러 코드 레퍼런스
| 에러 코드 | 설명 | 권장 조치 |
|---|---|---|
| 0 | 요청 성공 | — |
| 21007 | 유효하지 않은 API 키 | Authorization 헤더 형식이 Bearer $LISTENHUB_API_KEY인지 확인하고, 키가 정확히 복사되었는지 확인하세요 |
| 25002 | 리소스를 찾을 수 없음 | episodeId가 올바른지 확인하세요 |
| 25008 | 유효하지 않은 에피소드 상태 | 스크립트를 먼저 생성하는 워크플로에서만 발생합니다. 스크립트 생성이 끝난 뒤에 오디오 합성을 요청하세요. 팟캐스트 API 레퍼런스 참고 |
| 26004 | 크레딧 부족 | GET /v1/user/subscription을 호출해 잔액을 확인한 뒤 크레딧을 구매하세요 |
| 29003 | 유효하지 않은 파라미터 | 요청 페이로드를 API 레퍼런스와 대조해 확인하세요 |
| 29998 | 레이트 리밋 초과 | 3 RPM 제한을 초과했습니다 — 백오프 재시도를 구현하세요 |
| 91001 | 입력 콘텐츠가 너무 짧음 | 입력 콘텐츠의 길이를 늘리세요 |
| 91002 | 콘텐츠 정책 위반 | 콘텐츠가 정책에 맞는지 확인하세요 |
| 91003-91007 | 콘텐츠 생성 오류 | message 필드에서 상세 내용을 확인하세요 |
목록에 없는 0 이외의 에러 코드는 응답의 message 필드에서 상세 내용을 확인하거나 support@marswave.ai로 문의하세요.
에러 응답 형식
모든 에러 응답은 동일한 JSON 구조를 따릅니다:
{
"code": 21007,
"message": "Invalid API key",
"data": null
}자주 겪는 문제 해결
API 키 문제(21007):
Authorization헤더 형식이Bearer $LISTENHUB_API_KEY인지 확인하세요(Bearer 뒤에 공백이 필요합니다)- API 키가 빠짐없이 복사되었고 불필요한 공백이 없는지 확인하세요
- API 키 설정 페이지에서 키 상태를 확인하세요
레이트 리밋(29998):
- 생성 요청은 1분당 3회(3 RPM)로 제한됩니다
- 읽기 전용 요청은 이 제한의 대상이 아닙니다
- 지수 백오프 재시도를 구현하세요