오류 해결 가이드: 실리태번(SillyTavern)에서 발생하는 TavernAPI 에러 고치는 법

먼저 확인할 기본 설정

개별 오류 코드를 하나씩 찾아보기 전에, 실리태번(SillyTavern) 상단의 API Connections 패널(플러그 모양 아이콘)에서 아래 1분 체크리스트를 먼저 점검해 보세요. 사소한 입력 실수만 바로잡아도 대부분의 연결 문제는 즉시 해결됩니다.

1. Chat Completion Source: API를 Chat Completion으로 맞추고 Chat Completion Source를 Custom (OpenAI-compatible)으로 설정합니다.
2. Base URL: Custom Endpoint (Base URL) 칸에 https://tavernapi.com/v1을 입력합니다. 끝에 슬래시(/)나 /chat/completions를 붙이지 마세요.
   • 웹 앱 (JanitorAI): 전체 프록시 주소를 요구하는 웹 브라우저 프론트엔드는 예외입니다. 이 경우 https://tavernapi.com/v1/chat/completions를 입력하세요.
   • 실리태번 기본 리버스 프록시(Reverse Proxy): Custom 대신 실리태번의 기본 내장 소스로 연결한다면, Claude 소스는 Proxy Server URL을 https://tavernapi.com/v1로, Google AI Studio 소스는 https://tavernapi.com으로 설정합니다.
3. API 키: 발급받은 sk-tav-... 문자열 전체를 앞뒤 공백 없이 Custom API Key(기본 내장 소스에서는 Proxy Password) 칸에 붙여넣습니다.
4. 연결 및 모델 선택: Connect를 누르고 Available Models 드롭다운에서 모델을 선택합니다 (claude-opus-5-5, claude-sonnet-5-5, gemini-4-argon, gemini-3.8-flash, 또는 deepseek-v4-pro).
5. 계정 잔액: TavernAPI 콘솔을 열어 USD 기본 잔액이나 $0.30 무료 체험 크레딧이 0보다 큰지 확인합니다.

실리태번에서 TavernAPI 오류가 표시되는 방식

요청을 완료할 수 없을 때 TavernAPI는 다음과 같은 표준 JSON 구조로 응답합니다:

{"error": {"message": "...", "type": "...", "code": "..."}}

실리태번은 이 중 "message" 문구를 빨간색 팝업창으로 띄워 줍니다. 만약 팝업이 너무 빨리 사라진다면 실리태번 서버가 돌아가고 있는 콘솔 창(Windows의 명령 프롬프트, 안드로이드의 Termux)을 확인해 보세요. HTTP 상태 코드와 "code" 값이 함께 출력되어 있습니다.

오류 코드별 원인과 해결법

아래에서 화면에 뜬 HTTP 상태 코드와 메시지를 찾아 요청이 실패한 원인과 해결 방법을 확인하세요.

401 Invalid API key (유효하지 않은 API 키)

• 표시되는 내용: 메시지 Invalid API key, 코드 invalid_api_key. 키를 아예 보내지 않은 경우(키 입력칸이 비어 있을 때)에는 메시지가 Missing API key로 시작하며 코드는 missing_api_key입니다.
• 발생 원인: API 키 입력칸이 비어 있거나, sk-tav-... 키를 복사할 때 뒷부분이 잘렸거나, 앞뒤에 공백이 들어갔거나, 콘솔에서 이미 폐기된 키이거나, 다른 서비스(OpenRouter나 OpenAI 등)의 키를 넣었을 때 발생합니다.
• 해결 방법: 전체 sk-tav-... 키를 다시 복사해 붙여넣고 앞뒤에 실수로 들어간 공백이 없는지 확인하세요. 전체 키 문자열을 잃어버렸다면 콘솔의 API 키 탭을 열어 새 키를 생성하세요(보안상 각 키는 생성 직후 한 번만 표시되므로 즉시 복사해 두어야 합니다).
• 요금이 차감되나요? 아니요.

402 Insufficient balance (잔액 부족)

• 표시되는 내용: 메시지 Insufficient balance, 코드 insufficient_balance.
• 발생 원인: 현재 잔액(또는 무료 체험 크레딧)이 요청을 시작할 때 필요한 일시 홀드 금액보다 적기 때문입니다. TavernAPI는 프롬프트를 전달하기 전에 현재 확인되는 입력 토큰 비용에 Max Response Length(max_tokens, 최대 응답 길이) 전체를 해당 모델의 출력 단가로 계산한 예상 금액을 일시 홀드합니다. 그 후 답변이 끝나자마자 실제로 사용된 토큰만 정산하고 남은 홀드 금액은 즉시 해제합니다. 이 사전 승인 홀드 방식 때문에 잔액이 조금 남아 있더라도 402 오류가 뜰 수 있으며, 특히 Max Response Length를 아주 높게 잡아 두었거나 claude-opus-5-5처럼 단가가 높은 모델을 호출할 때 자주 나타납니다.
• 해결 방법:
  1. 실리태번의 AI Response Configuration(슬라이더 아이콘)을 열고 Max Response Length를 현실적인 수치(예: 1024 또는 2048 토큰)로 낮춰 사전 홀드 금액을 줄입니다.
  2. 드롭다운에서 gemini-3.8-flash나 deepseek-v4-pro처럼 단가가 더 낮은 모델로 변경합니다(모델별 요금표 참고).
  3. 또는 콘솔에서 잔액을 충전합니다.
• 요금이 차감되나요? 아니요.

403 체험 크레딧 제한 또는 프리셋 미해금

• 표시되는 내용: 아래 세 가지 403 메시지 및 코드 중 하나가 나타납니다:
  • 무료 체험 모델 제한: 메시지 Model "<id>" is not available with trial credit. Add credit to unlock it., 코드 trial_restricted.
  • 잠긴 프리셋 팩: 메시지 "<preset pack name>" is not included in your account. See https://tavernapi.com/console/presets(또는 This preset is currently unavailable), 코드 preset_locked.
  • 계정 상태: 메시지 Account suspended, 코드 account_banned.
• 발생 원인:
  • trial_restricted: $0.30 무료 체험 크레딧은 gemini-4-argon과 gemini-3.8-flash에서만 작동합니다. 체험 크레딧만 있는 계정에서 claude-opus-5-5, claude-sonnet-5-5, 또는 deepseek-v4-pro를 호출하면 이 오류가 발생합니다.
  • preset_locked: 현재 실리태번에 적용된 프리셋에 아직 내 계정에서 해금되지 않은 등급의 [[tav:...]] 플레이스홀더가 포함되어 있습니다.
  • account_banned: 계정 이용이 정지되었습니다(운영 정책(AUP) 참고).
• 해결 방법:
  • trial_restricted인 경우: 실리태번 모델 드롭다운에서 gemini-4-argon 또는 gemini-3.8-flash를 선택하거나, 콘솔에서 잔액을 충전해 모든 모델을 해금하세요.
  • preset_locked인 경우: 실리태번에서 개인 로컬 프리셋으로 전환하거나, Prompt Manager(프롬프트 매니저)에서 잠긴 [[tav:...]] 항목의 토글을 끄거나, https://tavernapi.com/console/presets에서 해당 프리셋을 해금하세요. Standard 프리셋은 첫 충전 시 해금되며, Pro 프리셋은 $4.99 단품 구매, 활성화된 $19 또는 $39 크레딧 팩, 또는 누적 충전 $25 달성 시 해금됩니다(TavernAPI 프리셋 작동 원리 참고).
  • account_banned인 경우: 계정 이메일을 적어 고객지원팀에 문의해 주세요.
• 요금이 차감되나요? 아니요.

404 Model not available (모델을 찾을 수 없음)

• 표시되는 내용: 메시지 Model "<id>" is not available, 코드 model_not_found.
• 발생 원인: 요청에 포함된 모델 ID에 오타가 있거나, 다른 서비스에서 쓰던 모델명이 그대로 남아 있거나(예: OpenRouter의 anthropic/claude-... 접두사 또는 예전 -story 접미사), 해당 모델이 일시적으로 비활성화되었을 때 발생합니다.
• 해결 방법: 실리태번에서 Connect를 눌러 모델 드롭다운 목록을 새로고침한 뒤 목록에서 다시 선택하세요. JanitorAI 등에서 모델 ID를 직접 타이핑해야 한다면 아래 다섯 가지 정확한 ID 중 하나를 입력하세요:
  • claude-opus-5-5
  • claude-sonnet-5-5
  • gemini-4-argon
  • gemini-3.8-flash
  • deepseek-v4-pro
• 요금이 차감되나요? 아니요.

404 Not found (잘못된 URL 경로)

• 표시되는 내용: 메시지 Not found, 코드 not_found.
• 발생 원인: 엔드포인트 URL 경로가 잘못되었습니다. 대개 /v1을 두 번 적었거나(https://tavernapi.com/v1/v1), 실리태번의 Custom Endpoint 칸에 /chat/completions까지 붙여넣었을 때(실리태번은 끝에 /chat/completions를 스스로 덧붙입니다) 발생합니다. 만약 /v1을 아예 빼먹었다면(https://tavernapi.com) 요청이 API가 아닌 일반 웹사이트로 전달되어 이 JSON 오류 대신 일반 404 웹페이지가 반환되지만, 해결 방법은 동일합니다.
• 해결 방법: 먼저 확인할 기본 설정에 안내된 대로, 사용 중인 프론트엔드에 맞는 정확한 URL로 수정하세요:

• 요금이 차감되나요? 아니요.

400 Bad request (잘못된 요청)

• 표시되는 내용: 아래 세 가지 400 메시지 및 코드 중 하나가 나타납니다:
  • model is required (코드 model_required)
  • messages must be a non-empty array (코드 messages_required)
  • Unknown preset block [[tav:...]]. Download the latest preset from https://tavernapi.com/console/presets (코드 preset_block_unknown)
• 발생 원인:
  • model_required: 메시지를 보내기 전에 모델을 선택하지 않았습니다.
  • messages_required: 전송된 요청 배열 안에 메시지가 하나도 없습니다(예: 프롬프트가 비어 있거나 정규식·확장 스크립트가 모든 메시지를 지워버린 경우).
  • preset_block_unknown: 로컬 프리셋 파일이 서버의 현재 프리셋 정의보다 오래된 구버전이거나, [[tav:...]] 태그를 임의로 수정했습니다.
• 해결 방법:
  • model_required인 경우, 실리태번에서 Connect를 누르고 드롭다운에서 모델을 선택하세요.
  • messages_required인 경우, 채팅방에 최소 한 개 이상의 메시지가 있는지 확인하고 프롬프트를 변형하는 확장 기능을 점검하세요.
  • preset_block_unknown인 경우, https://tavernapi.com/console/presets에서 최신 프리셋 JSON 파일을 다시 내려받아 실리태번에 임포트하세요.
• 요금이 차감되나요? 아니요.

429 요청 과다 또는 상위 서버 혼잡

• 표시되는 내용: 메시지 Upstream error (429), 유형 rate_limit_error, 코드 upstream_error.
• 발생 원인: 짧은 순간에 너무 많은 요청을 한꺼번에 보냈거나(예: 이전 턴의 응답이 아직 진행 중인데 재생성 버튼을 연타한 경우), 현재 상위 모델 제공사 서버가 혼잡하기 때문입니다. 상위 경로의 용량이 가득 차면 TavernAPI는 먼저 다른 우회 경로를 자동으로 시도한 뒤에도 자리가 없을 때만 429를 반환합니다.
• 해결 방법: 몇 초만 기다렸다가 스와이프하거나 답변을 재생성해 보세요.
• 요금이 차감되나요? 아니요—답변이 생성되지 않았을 때는 과금되지 않습니다.

5xx 서버 오류

• 표시되는 내용:
  • HTTP 502: 메시지 Upstream error (502), 코드 upstream_error
  • HTTP 503: 메시지 No upstream route is configured for this model, 코드 no_route
  • HTTP 500: preset_... 형태의 코드 (예: preset_block_error)
• 발생 원인:
  • Upstream error (502) (upstream_error): 요청 도중 상위 모델 제공사에 오류가 발생했거나 네트워크 연결이 끊겼습니다.
  • No upstream route is configured for this model (503, no_route): 구성된 모든 상위 경로에서 해당 모델을 일시적으로 사용할 수 없는 상태입니다.
  • 500 preset_... 코드 (preset_block_error 등): 잠금 처리된 프리셋 블록을 서버에서 펼치는 도중 서버 측 오류가 발생했습니다.
• 해결 방법:
  • 502 (upstream_error)인 경우: 몇 초 기다렸다가 스와이프하거나 재생성하세요.
  • 503 (no_route)인 경우: 경로가 복구되는 동안 드롭다운에서 다른 모델로 바꾸어 사용하세요.
  • 500 (preset_block_error)인 경우: 먼저 TavernAPI 프리셋을 끄고(또는 잠긴 [[tav:...]] 항목 토글을 끄고) 같은 채팅에서 답변 생성이 정상 작동하는지 확인한 뒤, 발생 시각과 모델 ID를 적어 고객지원팀에 문의해 주세요.
• 요금이 차감되나요? 답변 텍스트가 전혀 생성되기 전에 상위 제공사 오류가 발생했다면 홀드 금액이 전액 반환됩니다. 스트리밍이 시작된 후 답변 도중에 끊긴 경우에는 실제로 생성된 토큰만큼만 과금됩니다.

오류 코드 없이 발생하는 문제

실리태번 화면에 HTTP 오류 배너가 따로 뜨지 않는데도 채팅창 동작이 이상할 때가 있습니다.

Connect를 눌러도 빨간불이거나 모델 목록이 비어 있음

실리태번에서 Connect를 클릭했는데 상태 표시등이 계속 빨간색이거나 Available Models 드롭다운이 비어 있다면 다음을 확인하세요:

1. 먼저 확인할 기본 설정에 나온 소스, Base URL, API 키 설정을 다시 점검합니다.
2. URL이 https://로 시작하는지(http://가 아닌지), 그리고 https:// 앞이나 /v1 뒤에 공백이 들어가 있지 않은지 확인합니다.
3. 실리태번의 기본 내장 Claude 또는 Google AI Studio 소스를 쓰는 경우, Reverse Proxy(리버스 프록시) 항목을 펼쳐서 그 안의 Proxy Password 칸에 sk-tav-... 키를 넣었는지 확인하세요(그 위에 있는 직접 연결용 API 키 입력칸에 넣으면 작동하지 않습니다). 각 입력칸의 정확한 위치는 실리태번 연동 가이드에서 확인할 수 있습니다.

답변이 비어 있거나 문장 중간에 잘림

캐릭터의 대사가 문장 한가운데서 뚝 끊기거나 아예 빈 말풍선으로 돌아온다면 다음 두 가지 원인을 확인하세요:

• Max Response Length가 너무 낮게 설정됨: 실리태번 AI Response Configuration 패널의 Max Response Length(max_tokens, 최대 응답 길이)에 도달하는 즉시 답변 출력이 멈춥니다. 특히 답변을 쓰기 전에 먼저 추론(Thinking)을 거치는 모델들은 실제 눈에 보이는 답변을 작성하기 전에 내부 추론 과정에 해당 토큰 예산을 먼저 사용합니다. 만약 Max Response Length가 너무 낮게(예: 250 또는 400) 설정되어 있으면, 모델이 내부 추론에만 토큰 예산을 다 써버려서 정작 화면에 보이는 답변은 비어 있을 수 있습니다. Max Response Length를 충분히 높인 뒤(예: 1024~2048 토큰) 다시 생성해 보세요.
• 상위 제공사의 안전 필터: 프롬프트가 모델 제공사의 자체 안전 분류기 기준에 걸린 경우에도 답변이 일찍 종료되거나 빈 메시지가 반환될 수 있습니다.

프리셋이 적용되지 않거나 [[tav:...]] 텍스트가 그대로 보임

잠금 처리된 프리셋 플레이스홀더([[tav:...]])는 요청이 TavernAPI 서버를 통과할 때만 실제 지시문으로 펼쳐집니다. 답변에 프리셋 규칙이 반영되지 않거나 [[tav:...]] 문자열이 그대로 보인다면 다음을 확인하세요:

1. API Connections(플러그 아이콘)를 열고 현재 활성화된 연결이 https://tavernapi.com/v1을 가리키고 있는지 확인합니다(TavernAPI 프리셋을 켜 둔 채로 다른 API 제공사에 연결되어 있지 않은지 점검하세요).
2. AI Response Configuration(슬라이더 아이콘)을 열고 Chat Completion Presets 드롭다운에서 TavernAPI 프리셋이 선택되어 있는지, 그리고 핵심 프롬프트 항목들의 토글이 켜져 있는지 확인합니다.
3. 프리셋이 업데이트된 후에는 로컬 파일과 서버 정의가 일치하도록 https://tavernapi.com/console/presets에서 프리셋 JSON을 다시 내려받아 새로 임포트하세요. 자세한 내용은 TavernAPI 프리셋 작동 원리를 참고하세요.

예상보다 사용 요금이 많이 나옴

롤플레잉에서는 실리태번이 매 턴마다 이전 대화 기록과 캐릭터 카드, 프리셋을 함께 다시 전송합니다. TavernAPI는 서버 측 자동 프롬프트 캐싱으로 이 입력 비용을 대폭 줄여주므로, 평소보다 요금이 많이 나왔다면 거의 항상 **프롬프트 캐시 미스(Cache miss)**가 발생했거나 대화가 아주 길어졌기 때문입니다:

• 오랜만에 돌아와 첫 메시지를 보낼 때: 상위 제공사들은 대화가 멈춘 뒤 몇 분 동안만 캐시된 앞부분(Prefix)을 보관합니다. 길게 쉬었다가 돌아와 보내는 첫 턴은 캐시를 새로 작성해야 하므로 비용이 눈에 띄게 더 들며, 바로 이어지는 다음 턴부터는 다시 할인된 캐시 읽기 단가로 내려갑니다.
• 이전 메시지를 수정하거나 프롬프트 상단 항목이 바뀔 때: 앞선 대화 메시지를 수정·삭제하거나, 대화 도중 프리셋을 바꾸거나, 프롬프트 맨 위쪽에 랜덤 매크로({{random}}, {{roll}})를 넣어두면 앞부분 내용이 달라져 매번 캐시를 새로 쓰게 됩니다.
• 정리하지 않은 초장문 컨텍스트: 캐싱이 정상 작동하더라도 100k 토큰을 넘긴 장기 채팅방은 20k 토큰짜리 채팅방보다 매 턴당 비용이 더 많이 듭니다.

캐시 적중률을 높게 유지하는 팁은 프롬프트 캐싱 가이드에서 읽어보실 수 있으며, 콘솔의 사용량 페이지에서 요청별 정확한 입력·캐시·출력 토큰 수를 직접 확인해 보세요.

충전 및 결제 문제

TavernAPI의 암호화폐 충전은 NOWPayments 결제창을 통해 $6부터 $500까지 1달러 단위로 진행됩니다(암호화폐 결제 가이드 참고). 콘솔의 결제 내역 페이지에서는 각 암호화폐 주문이 대기 중(Pending), 부분 결제(Partially paid), 결제 완료(Paid), 만료됨(Expired), 또는 실패(Failed) 다섯 가지 상태 중 하나로 표시됩니다.

청구 금액보다 적게 입금됨

보통 이용 중인 거래소(Exchange)나 지갑에서 출금 수수료를 별도로 더하지 않고, 보내는 금액에서 차감해 송금했을 때 이런 현상이 발생합니다.

• 주문 상태가 부분 결제(Partially paid)로 바뀌며, 실제로 도착한 금액만큼 비율에 맞춰 자동으로 잔액에 반영됩니다.
• 부족한 나머지 금액을 채우려면 콘솔에서 새 충전 주문을 만들어 결제하세요.
• 고객지원팀이 별도로 안내하지 않는 한, 이전 입금 주소로 두 번째 송금을 보내지 마세요.

주문 상태가 만료됨(Expired)으로 표시됨

입금되지 않은 암호화폐 주문은 1시간이 지나면 자동으로 닫히며 상태가 만료됨(Expired)으로 바뀝니다. 만약 이미 송금을 마쳤는데 블록체인 네트워크 처리가 늦어져 1시간이 지난 뒤에 입금이 도착하더라도, 확인되는 즉시 잔액에 자동으로 정상 반영됩니다.

충전한 잔액이 아직 들어오지 않음

블록체인 네트워크 승인은 보통 몇 분이면 끝나지만, 네트워크가 혼잡하거나 거래소의 일괄 출금 처리가 지연되면 시간이 더 걸릴 수 있습니다. 트랜잭션 승인이 완료되면 콘솔 결제 내역의 상태가 자동으로 업데이트됩니다.

약 30분이 지나도 상태에 변화가 없다면 아래 정보를 적어 고객지원팀에 문의해 주세요:

• 트랜잭션 해시 (TXID)
• 사용한 코인 및 네트워크
• 송금한 금액
• TavernAPI 계정 이메일 주소

청구 금액보다 더 많이 송금함

결제 금액이 청구서의 주문 금액을 초과한 경우, 원래 청구된 주문 금액만큼만 자동으로 충전되며 초과분은 스스로 합산되지 않습니다. 트랜잭션 해시(TXID)와 계정 이메일을 적어 고객지원팀에 문의해 주시면 입금 내역을 확인한 뒤 초과 금액을 잔액에 추가해 드립니다.

네트워크나 코인을 잘못 선택해 송금함

결제창에서 선택한 것과 다른 블록체인 네트워크로 송금했거나 다른 코인을 보낸 경우, 즉시 트랜잭션 해시(TXID), 코인, 네트워크, 송금 금액을 적어 고객지원팀에 문의해 주세요. 단, 잘못 송금된 자산의 복구는 보장되지 않습니다.

아직 해결되지 않았나요?

위의 방법으로 문제가 해결되지 않았다면 문의 페이지를 통해 아래 정보를 함께 보내주세요. 서버 로그를 즉시 확인해 도와드리겠습니다:

• API 또는 프리셋 오류 문의 시: TavernAPI 계정 이메일 주소, 사용한 모델 ID(claude-opus-5-5, claude-sonnet-5-5, gemini-4-argon, gemini-3.8-flash, 또는 deepseek-v4-pro), 대략적인 발생 시각(시간대 포함), HTTP 상태 코드와 오류 code, 그리고 프리셋 사용 중이었다면 해당 프리셋 팩 이름.
• 결제 문제 문의 시: 계정 이메일 주소, 트랜잭션 해시(TXID), 사용한 코인과 네트워크, 송금한 금액.