막히셨을 때
여기서 찾으시면 됩니다

대부분 결제수단이 등록되지 않은 경우입니다.

console.upstage.ai → Dashboard → Billing 에서 카드를 등록하신 뒤 다시 실행해 주세요. 크레딧이 남아 있는 동안에는 크레딧이 먼저 사용됩니다.

키가 제대로 전달되지 않았다는 뜻입니다. 아래 순서로 확인해 주세요.

1. 키 앞에 Bearer를 붙이셨는지 확인합니다.
2. 키를 복사하실 때 앞뒤에 공백이나 따옴표가 함께 들어가지 않았는지 확인합니다.
3. 키가 up_으로 시작하는지 확인합니다.
4. 콘솔에서 키를 다시 발급받아 교체해 보십니다.

Colab의 보안 비밀 설정을 확인해 주세요.

1. 왼쪽 열쇠(🔑) 아이콘에서 이름이 정확히 UPSTAGE_API_KEY인지 확인합니다. 대소문자와 밑줄까지 같아야 합니다.
2. 해당 비밀의 노트북 액세스 토글이 켜져 있는지 확인합니다.
3. 토글을 켜신 뒤에는 첫 셀을 다시 실행해 주셔야 반영됩니다.

VPN이나 광고 차단 프로그램이 절차를 막는 경우가 있습니다. 두 가지를 잠시 꺼 두신 뒤 다시 시도해 보시기 바랍니다.

기관 내부망을 사용하고 계시다면 방화벽 정책도 함께 확인해 주세요.

호출 한도를 넘었다는 신호이며, 고장이 아닙니다. Tier 0 기준은 분당 100회 · 50,000 토큰입니다.

• 곧바로 다시 보내지 마시고 몇 초 기다린 뒤 실행합니다. 그래도 같다면 기다리는 시간을 늘립니다.
• 동시에 실행하는 개수를 줄입니다.
• 수업 중이시라면 조를 나누어 차례로 진행합니다.

429 응답에는 X-Upstage-RateLimit-Retry-After-Requests가 담겨 옵니다. 여기 적힌 시각 이후에 보내시면 됩니다.

Document Parse는 초당 1건(동기 방식)이 기준입니다. 한꺼번에 보내시면 기준을 넘기게 됩니다.

한 건 처리 후 1초 정도 간격을 두고 보내 주세요. 그리고 어디까지 처리되었는지 기록해 두시면, 실패한 건부터 다시 시작하실 수 있습니다. Part 3의 반복 처리 예제를 참고하시면 됩니다.

분당 100회 기준이라, 30명이 동시에 여러 번 실행하면 금방 넘어섭니다.

• 조를 나누어 시간 차를 두고 진행해 주세요.
• 실습 전에 한 번 시연해 보시면 속도를 가늠하실 수 있습니다.
• 학생마다 다른 계정을 사용하는 경우에는 한도가 계정별로 적용됩니다.

크레딧을 추가로 구매하시면 등급이 올라가면서 한도도 함께 늘어납니다. 올라간 등급의 한도는 콘솔의 Billing → Commitment → Rate limit에서 확인하실 수 있습니다.

기관 단위로 큰 규모가 필요하시다면 Upstage 고객 지원으로 문의하시면 됩니다.

세 가지 경우가 있습니다.

첫째, 지원 범위 밖의 모델을 요청하신 경우입니다. 언어 모델 중 무상 지원 대상은 solar-pro2 · solar-pro3 · solar-pro4입니다. solar-mini처럼 그 밖의 모델을 부르시면 이 응답을 받게 됩니다.

둘째, 주소가 다른 경우입니다. 제품마다 요청을 보내는 주소가 다릅니다. 모델 이름 문제처럼 보이지만 실제 원인은 주소인 경우가 많습니다.

셋째, 2026년 10월 중순 이후에 solar-pro2를 부르신 경우입니다. Solar Pro 2는 이 시점에 지원이 끝나 더 이상 호출되지 않습니다. 이때도 solar-pro4로 바꾸시면 됩니다.

모델 이름만 바꾸시면 됩니다. 사용법·속도·비용이 같아 다른 설정은 그대로 두셔도 됩니다.

2026년 10월 중순 전에는 옮겨 두시기를 권합니다. Solar Pro 2는 그때 지원이 종료되어 이후에는 호출 자체가 되지 않습니다. 나중에 급하게 고치시는 것보다 미리 바꿔 두시는 편이 편합니다.

다만 답변의 표현이나 정리 방식이 조금 달라질 수 있으므로, 형식을 지정해 두셨다면 결과를 한 번 확인해 주세요.

무상 지원 대상이 아닌 모델을 부르고 계실 가능성이 높습니다. 이 프로그램이 지원하는 것은 solar-pro2 · solar-pro3 · solar-pro4 · document-parse 네 가지뿐입니다.

이름이 비슷해 헷갈리기 쉬운 information-extract · document-classify와 임베딩 계열(solar-embedding-2-query · solar-embedding-2-passage)은 모두 별도 과금 제품입니다. 동작은 정상이라 오류가 나지 않고 크레딧만 조용히 줄어듭니다.

코딩 에이전트에게 코드를 맡기셨다면 특히 확인해 보세요. 항목 추출을 시키면 information-extract를 고르는 경우가 잦습니다. 같은 일을 무상 범위에서 하는 방법은 Part 3 · 지원 범위 밖 기능에 있습니다.

Solar 예제를 그대로 가져오신 경우입니다. 두 제품은 응답 구조가 다릅니다.

Solar는 choices[0].message.content에서 꺼내지만, Document Parse 응답에는 choices가 아예 없습니다. content.html · content.markdown · elements[]에서 꺼내 주세요.

사용량 단위도 다릅니다. Solar는 usage.total_tokens(토큰), Document Parse는 usage.pages(페이지)입니다. 비교표는 Part 3 · 문서 다루기에 있습니다.

언어 모델의 특성상 표현이 매번 같지는 않습니다. 결과를 일정하게 만드시려면 아래 방법이 도움이 됩니다.

• 형식을 지정합니다. Part 3의 방법을 쓰시면 항목 이름과 형태가 고정됩니다.
• 고를 수 있는 값을 정해 둡니다. 판단 결과를 enum으로 묶으면 정해진 값만 나옵니다.
• 기준을 숫자와 조건으로 적습니다. "적절히 판단"보다 "10만 원 초과 시 보류"가 훨씬 안정적입니다.

문서의 화질이나 처리 방식을 확인해 주세요.

1. OCR을 Force로 바꿔 다시 실행해 보십니다. 스캔본과 사진에서 특히 효과가 있습니다.
2. 문서 너비가 640픽셀 이상인지 확인합니다. 너무 작으면 인식이 어렵습니다.
3. 가장 작은 글씨가 이미지 높이의 2.5% 이상인지 확인합니다.
4. 표와 그림이 복잡하다면 Enhanced 방식으로 바꿔 봅니다.

아래 세 가지를 확인해 주세요.

• 형식: JPEG · PNG · BMP · PDF · TIFF · HEIC · DOCX · PPTX · XLSX · HWP · HWPX를 지원합니다.
• 크기: 50MB 이하여야 합니다.
• 파일명: 너무 길면 문제가 될 수 있으므로 짧게 바꿔 보십니다.

동기 방식은 한 파일에 100페이지까지 처리하며, 그보다 긴 문서는 앞의 100페이지만 처리됩니다.

문서를 나누어 보내시거나, 1,000페이지까지 지원하는 비동기 방식을 사용해 주세요.

표가 여러 쪽에 걸쳐 이어진다면 Merge Multipage Tables 설정을 켜 주세요.

차트 안의 수치가 필요하시다면 Chart recognition을 함께 확인해 주세요.

결과는 content.html에서 표 구조 그대로 확인하실 수 있습니다.

판단의 근거가 될 자료를 함께 넣지 않으신 경우가 많습니다.

확인이 필요한 사실은 문서나 규정을 프롬프트에 함께 담아 주세요. 그리고 "이 자료에 없는 내용은 추측하지 말고 '자료에서 찾을 수 없습니다'라고 답해 주세요"를 덧붙이시면 크게 개선됩니다.

두 가지를 확인해 주세요.

첫째, 그 정보가 문서에 실제로 있는지 확인합니다. 없는 값은 비어 나오는 것이 정상입니다.

둘째, 설명이 충분히 구체적인지 확인합니다. "금액"보다 "부가세를 포함한 최종 결제 금액"이 훨씬 잘 찾습니다. 문서에서 그 값이 어디에 있는지 함께 적어 주시면 더 좋습니다.

읽기 전에 finish_reason을 확인해 주세요.

stop이면 끝까지 만들어진 상태입니다. length라면 분량 한계에 걸려 중간에서 잘린 상태이므로 읽을 수 없습니다. 이때는 max_tokens를 늘리시거나 다시 요청해 주세요.

형식을 지정하실 때 strict를 true, additionalProperties를 false로 두셨는지도 확인해 주세요.

모델이 알지 못하는 사실을 물으면 그럴듯한 답을 만들어 낼 수 있습니다.

• 근거가 될 자료를 함께 넣어 주세요.
• 답변과 함께 근거가 된 부분(페이지 번호나 인용문)을 적게 하시면 확인이 쉬워집니다.
• 모르는 것은 모른다고 답하도록 프롬프트에 적어 주세요.
• 금액·날짜·이름처럼 중요한 값은 사람이 원문과 대조해 주세요.

대부분 설명이 모호한 경우입니다. 모델은 도구의 설명을 보고 언제 부를지 판단합니다.

"데이터 조회"보다 "부서와 연도로 예산 집행 현황을 조회합니다"처럼 언제 쓰는 도구인지 구체적으로 적어 주세요.

참고로, 인사말처럼 도구가 필요 없는 질문에 부르지 않는 것은 정상입니다. 도구가 꼭 필요한 질문으로 먼저 확인해 보세요.