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 — 언제, 어떻게 써야 할까? 를 다루겠습니다.