2pyeon Api Ereokodeu Wanjeon Haebu

Solutions

Resources

Company

Pricing

Try now Try demo

Contact us

en

비즈니스의 미래를 선도하는 인공지는 솔루션

비즈니스 고민을 해결할 생성형 AI 모델이 필요하신가요?

업스테이지의 AI전문가와 함께 시작하세요!

✕

API를 사용하다 보면 가장 먼저 맞닥뜨리는 것이 에러 코드입니다. 예상치 못한 응답을 받으면 당황하기 쉽지만, 사실 대부분은 원인을 확인하고 몇 가지 사항만 점검하면 빠르게 해결할 수 있습니다. 이 글에서는 Upstage API에서 자주 발생하는 에러 코드를 정리하고, 각각의 원인과 해결 방법을 안내드립니다.

🔑 인증 및 권한 관련 401 Unauthorized 원인 잘못된 API Key 또는 Authorization 헤더 오류

확인 사항 API Key가 요청 헤더에 포함되어 있는지 확인 Authorization: Bearer API_KEY 형식이 맞는지 점검 콘솔에서 해당 API Key가 삭제된 것은 아닌지 확인 오타, 따옴표, 공백 등 단순 실수가 없는지 검토

403 Forbidden 원인 사용 가능한 크레딧 부족 결제 실패 내부 정책에 따른 특정 IP 차단

해결 방법 콘솔에서 크레딧 잔액 확인 등록된 결제 수단이 정상인지 확인 문제가 지속되면 지원센터 로 문의

📄 요청 형식 관련 400 Bad Request Solar APIs JSON 구문 오류 필수 키 누락 키 이름이나 값 타입 불일치 값 오류 또는 오타

Document AI APIs 파일 경로 오류 지원하지 않는 파일 포맷 업로드 50MB를 초과하는 파일

404 Not Found 원인 : 잘못된 URL Path 해결 방법 : 요청 경로를 다시 확인

405 Method Not Allowed 원인 :  http method (GET, POST, 등) 중에 저희가 허용하지 않은 method 로 요청하는 경우에 발생 해결 방법 : docs 에서 호출하려는 API 의 url 과 method 가 정확한지 확인 후, 맞는 url, method 로 요청

⏱️ Rate Limit 및 과부하 429 Too Many Requests 원인 : 초당 요청 수(RPS) 또는 분당 토큰 수(TPM), 또는 분당 요청 수(RPM) 제한 초과 해결 방법 요청 간격을 늘리거나 큐를 통해 순차 처리 Rate Limit 증가 신청 가능

💥 서버/시스템 오류 500 Internal Server Error 원인 : 일시적인 서버 오류, Document Parse Async 처리 실패 해결 방법 : 잠시 후 재시도 → 문제가 반복되면 상태 페이지 확인 후 지원센터 문의

502 / 503 / 504 원인 : 게이트웨이/서비스 가용성 문제 해결 방법 일시적 장애일 가능성이 높음 요청을 재시도하고, 동일 현상이 지속되면 지원센터로 문의

🧩 Document Parse Async 특수 사례 403 Client Error (download_url 만료) download_url은 발급 후 약 15분간만 유효 원래 request_id 로 다시 조회하면 새 URL 발급 (추가 과금 없음)

“Failed to process document” 파일명이 지나치게 긴 경우 (한글 ≤ 300자, 영문 ≤ 900자 권장) 문서 구조나 형식에 따른 처리 제한 Technical support 신청 을 통해 지원팀에 request_id 와 샘플 문서를 전달하면 빠른 원인 파악을 위한 도움을 받을 수 있음

요약 400 : 요청 형식 오류 (JSON/파일 경로/50MB 제한) 401 : API Key 또는 Authorization 헤더 문제 403 : 크레딧 부족, 결제 실패, IP 차단 404/405 : 잘못된 URL Path, http 대신 https 필요 429 : Rate Limit 초과 → 요청 빈도 조정 및 상향 신청 가능 500~504 : 서버/게이트웨이 오류 → 재시도 후 지속 시 지원센터 문의 Document Parse Async 특수 케이스 : download_url 만료, 파일명·문서 구조 문제

Quick FAQ Recap Q. 400 Bad Request가 자주 발생하는 이유는 무엇인가요? A. 파일 경로·형식·크기(50MB 이하)를 점검하세요. Q. 401 Unauthorized는 어떻게 해결할 수 있나요? A. Authorization 헤더를 "Bearer API_KEY" 형태로 정확히 입력했는지 확인해 주세요. Q. 403 Forbidden은 언제 발생하나요? A. 크레딧 부족, 결제 실패, 또는 특정 IP 차단 시 발생합니다. Q. 404 / 405 에러는 무엇을 의미하나요? A. 잘못된 URL Path 또는 http 요청 때문입니다. https 프로토콜을 사용하고 경로를 다시 확인하세요. Q. 429 Too Many Requests를 줄이려면 어떻게 해야 하나요? A. 요청 빈도를 낮추고, 필요할 경우 Rate Limit 증가를 요청하세요. Q. 500 / 502 / 503 / 504 에러는 어떻게 대응해야 하나요? A. 대부분 일시적인 서버 장애입니다. 잠시 후 재시도하고, 문제가 계속되면 지원센터로 문의하세요. Q. Document Parse에서 403 Client Error가 발생하는 이유는 무엇인가요? A. download_url 유효기간이 만료된 경우입니다. 원래 request_id로 다시 조회하면 새로운 URL을 받을 수 있습니다.

👉 다음 편에서는 많은 분들이 헷갈려 하시는 OCR vs Document Parse — 언제, 어떻게 써야 할까? 를 다루겠습니다.

Related blog posts

Browse all articles

Company June 26, 2026

AI Native 조직의 조건 ② — 직군 경계의 재건축

Industry June 25, 2026

AI Native 인재의 조건 ① — 학습 속도와 스트레스 매니징

Company June 2, 2026

모델 성능 경쟁은 끝났다 — 엔터프라이즈 AI의 진짜 병목은 '문서 구조화'다

비즈니스의 미래를 선도하는 인공지능 솔루션

비즈니스 고민을 해결할 생성형 AI 모델이 필요하신가요?

업스테이지의 AI전문가와 함께 시작하세요!

제품 문의 바로 가기

콘솔에서 바로 시작하기

API를 사용하다 보면 가장 먼저 맞닥뜨리는 것이 에러 코드입니다. 예상치 못한 응답을 받으면 당황하기 쉽지만, 사실 대부분은 원인을 확인하고 몇 가지 사항만 점검하면 빠르게 해결할 수 있습니다. 이 글에서는 Upstage API에서 자주 발생하는 에러 코드를 정리하고, 각각의 원인과 해결 방법을 안내드립니다.

🔑 인증 및 권한 관련 401 Unauthorized 원인 잘못된 API Key 또는 Authorization 헤더 오류

확인 사항 API Key가 요청 헤더에 포함되어 있는지 확인 Authorization: Bearer API_KEY 형식이 맞는지 점검 콘솔에서 해당 API Key가 삭제된 것은 아닌지 확인 오타, 따옴표, 공백 등 단순 실수가 없는지 검토

403 Forbidden 원인 사용 가능한 크레딧 부족 결제 실패 내부 정책에 따른 특정 IP 차단

해결 방법 콘솔에서 크레딧 잔액 확인 등록된 결제 수단이 정상인지 확인 문제가 지속되면 지원센터 로 문의

📄 요청 형식 관련 400 Bad Request Solar APIs JSON 구문 오류 필수 키 누락 키 이름이나 값 타입 불일치 값 오류 또는 오타

Document AI APIs 파일 경로 오류 지원하지 않는 파일 포맷 업로드 50MB를 초과하는 파일

404 Not Found 원인 : 잘못된 URL Path 해결 방법 : 요청 경로를 다시 확인

405 Method Not Allowed 원인 :  http method (GET, POST, 등) 중에 저희가 허용하지 않은 method 로 요청하는 경우에 발생 해결 방법 : docs 에서 호출하려는 API 의 url 과 method 가 정확한지 확인 후, 맞는 url, method 로 요청

⏱️ Rate Limit 및 과부하 429 Too Many Requests 원인 : 초당 요청 수(RPS) 또는 분당 토큰 수(TPM), 또는 분당 요청 수(RPM) 제한 초과 해결 방법 요청 간격을 늘리거나 큐를 통해 순차 처리 Rate Limit 증가 신청 가능

💥 서버/시스템 오류 500 Internal Server Error 원인 : 일시적인 서버 오류, Document Parse Async 처리 실패 해결 방법 : 잠시 후 재시도 → 문제가 반복되면 상태 페이지 확인 후 지원센터 문의

502 / 503 / 504 원인 : 게이트웨이/서비스 가용성 문제 해결 방법 일시적 장애일 가능성이 높음 요청을 재시도하고, 동일 현상이 지속되면 지원센터로 문의

🧩 Document Parse Async 특수 사례 403 Client Error (download_url 만료) download_url은 발급 후 약 15분간만 유효 원래 request_id 로 다시 조회하면 새 URL 발급 (추가 과금 없음)

“Failed to process document” 파일명이 지나치게 긴 경우 (한글 ≤ 300자, 영문 ≤ 900자 권장) 문서 구조나 형식에 따른 처리 제한 Technical support 신청 을 통해 지원팀에 request_id 와 샘플 문서를 전달하면 빠른 원인 파악을 위한 도움을 받을 수 있음

요약 400 : 요청 형식 오류 (JSON/파일 경로/50MB 제한) 401 : API Key 또는 Authorization 헤더 문제 403 : 크레딧 부족, 결제 실패, IP 차단 404/405 : 잘못된 URL Path, http 대신 https 필요 429 : Rate Limit 초과 → 요청 빈도 조정 및 상향 신청 가능 500~504 : 서버/게이트웨이 오류 → 재시도 후 지속 시 지원센터 문의 Document Parse Async 특수 케이스 : download_url 만료, 파일명·문서 구조 문제

Quick FAQ Recap Q. 400 Bad Request가 자주 발생하는 이유는 무엇인가요? A. 파일 경로·형식·크기(50MB 이하)를 점검하세요. Q. 401 Unauthorized는 어떻게 해결할 수 있나요? A. Authorization 헤더를 "Bearer API_KEY" 형태로 정확히 입력했는지 확인해 주세요. Q. 403 Forbidden은 언제 발생하나요? A. 크레딧 부족, 결제 실패, 또는 특정 IP 차단 시 발생합니다. Q. 404 / 405 에러는 무엇을 의미하나요? A. 잘못된 URL Path 또는 http 요청 때문입니다. https 프로토콜을 사용하고 경로를 다시 확인하세요. Q. 429 Too Many Requests를 줄이려면 어떻게 해야 하나요? A. 요청 빈도를 낮추고, 필요할 경우 Rate Limit 증가를 요청하세요. Q. 500 / 502 / 503 / 504 에러는 어떻게 대응해야 하나요? A. 대부분 일시적인 서버 장애입니다. 잠시 후 재시도하고, 문제가 계속되면 지원센터로 문의하세요. Q. Document Parse에서 403 Client Error가 발생하는 이유는 무엇인가요? A. download_url 유효기간이 만료된 경우입니다. 원래 request_id로 다시 조회하면 새로운 URL을 받을 수 있습니다.

👉 다음 편에서는 많은 분들이 헷갈려 하시는 OCR vs Document Parse — 언제, 어떻게 써야 할까? 를 다루겠습니다.

Related blog posts

Browse all articles

Tutorials August 31, 2025

Upstage MCP Server 지원

Tutorials August 29, 2025

AI Capabilities 완전 정복: 단순 채팅을 넘어선 AI 활용법

Tutorials August 25, 2025

Upstage 개발자 FAQ 시리즈 2편: API 에러코드 완전 해부

document.addEventListener("DOMContentLoaded", function () { const sets = document.querySelectorAll(".ab-test-topbar-set");

if (sets.length === 0) return;

const randomIndex = Math.floor(Math.random() * sets.length);

sets.forEach((set, idx) => { set.style.display = idx === randomIndex ? "block" : "none"; // 또는 "inline-flex", 레이아웃에 따라 조정 }); });

태그 바로 앞에 삽입 -->

×

document.addEventListener("DOMContentLoaded", function () { var modal = document.getElementById('elfsightModal'); if (modal && modal.parentNode !== document.body) { document.body.appendChild(modal); } });