이 문서는 영어 원문을 자동 번역한 것으로, 내용이 원문과 다를 수 있습니다.영어 원문 보기
이 페이지는 자주 발생하는 문제를 빠르게 파악하고 해결할 수 있도록 각 에러 코드에 대한 자세한 설명을 제공해요. 에러가 발생하면 이 가이드를 참고하고 권장되는 해결 단계를 따라주세요.
에러 응답 형식
API 가 반환하는 에러는 아래 형태의 JSON 본문을 함께 내려줘요.
에러 처리 분기는 message 가 아니라 code 를 기준으로 작성해주세요. code 는 값이 유지되는 식별자이고, message 문구는 바뀔 수 있어요.
일부 응답에는 이 본문이 없어 code 도 없어요. 라우팅 전에 차단되는 경로, 지원하지 않는 HTTP 메서드, 요청을 처리하는 서비스에서 발생한 오류가 그런 경우예요. 해당 행은 아래 표에 — 로 표시했어요.
에러 코드
| HTTP 상태 | 에러 코드 | 원인 | 해결 방법 |
|---|---|---|---|
| 400 | invalid_request_body | 요청 본문의 형식 또는 데이터가 올바르지 않거나, 유효하지 않거나 서비스가 종료된 모델을 지정함 | Solar API 의 경우: • 요청 본문의 JSON 구문이 올바른지 확인해주세요 • required 키가 모두 요청 본문에 포함되어 있는지 확인해주세요 • model 파라미터가 포함되어 있고 사용 가능한 모델인지 확인해주세요 • 요청 본문의 모든 키가 올바른지 확인해주세요 • 요청 본문의 모든 값이 올바른 타입인지 확인해주세요 • 오타가 없는지 확인해주세요! Document AI API 의 경우: • 요청 본문의 문서 파일 위치가 올바른지 확인해주세요 • 문서 파일이 지원되는 형식인지 확인해주세요 • 문서 파일이 50MB(52,428,800바이트) 이하인지 확인해주세요 |
| 400 | invalid_path | 요청 URL 에 줄바꿈 등 제어 문자가 포함됨 | • 경로와 쿼리 파라미터에서 의도하지 않은 문자를 제거해주세요 |
| 401 | invalid_api_key | 유효하지 않거나 삭제된 API 키, 또는 API 키 누락 | • 요청 헤더에 API 키를 설정했는지 확인해주세요 • Authorization 헤더가 “Bearer API_KEY” 형식인지 확인해주세요 • 콘솔에서 해당 API 키가 삭제되지 않았는지 확인해주세요 • 오타가 없는지 확인해주세요! |
| 401 | api_key_is_blocked | API 키 자체는 유효하지만 차단된 상태예요. 크레딧 잔액이 없고 결제 수단이 등록되지 않은 경우가 가장 많아요 | • 결제 수단을 등록하거나 크레딧을 충전해주세요 • API 키를 새로 발급해도 해결되지 않아요 • 결제 수단이 이미 등록되어 있다면 지원팀에 문의해주세요 |
| 403 | api_key_is_not_allowed | 크레딧 부족으로 API 키 사용이 중지됨 | • 결제 수단을 등록하거나 크레딧을 충전해주세요 |
| 403 | studio_subscription_quota_exceeded | 조직의 스튜디오 사용량을 모두 사용함. 스튜디오 워크플로우를 실행하는 요청에서 반환되며, 이 경우 콘솔 크레딧이 아니라 스튜디오 사용량이 차감됨 | • 스튜디오 조직 설정의 사용량 페이지에서 초기화 시점을 확인해주세요 • 요금제를 구독하거나 상위 요금제로 전환해주세요 • Free 요금제는 다음 날 사용량이 초기화됩니다. 사용량을 다 썼을 때 참고 |
| 403 | data_residency_region_mismatch | 조직이 한국 리전에서만 데이터를 처리하도록 설정됐는데, api.upstage.ai 처럼 한국 리전 밖의 엔드포인트로 요청함. 한국 리전 사용을 승인받은 조직에만 해당함 | • kr.api.upstage.ai 로 요청을 보내주세요. 리전 엔드포인트 참고 |
| 404 | invalid_path / — | 잘못된 URL 경로. 어떤 엔드포인트와도 일치하지 않는 경로는 라우팅 전에 차단되어 JSON 본문이 없어요 | • 요청 경로가 API 레퍼런스와 일치하는지 확인해주세요 |
| 405 | — | 해당 엔드포인트에서 허용하지 않는 HTTP 메서드. POST 전용 엔드포인트에 GET 을 보낸 경우가 그 예예요 | • 엔드포인트가 요구하는 HTTP 메서드를 확인해주세요 • http:// 로 보낸 요청은 301 로 https:// 에 리다이렉트돼요. 클라이언트가 리다이렉트를 따르지 않는다면 https:// 로 직접 호출해주세요 |
| 413 | payload_too_large | 요청 본문이 500MB(500,000,000바이트) 이상 | • 요청 본문 크기를 줄여주세요 • 요청을 더 작은 단위로 나눠서 보내주세요 |
| 413 | — | 업로드한 문서가 50MB(52,428,800바이트)보다 큼. Document AI 서비스가 반환해요 | • 문서 파일이 50MB 이하인지 확인해주세요 • 문서를 더 작은 파일로 나눠주세요 |
| 415 | — | 해당 작업이 지원하지 않는 파일 형식. Document AI 서비스가 반환해요 | • 변환, 분할, 추출에 지원되는 파일 형식인지 확인해주세요 • 지원되는 파일 형식을 사용해주세요 |
| 422 | — | 문서가 손상되었거나 깨짐. Document AI 서비스가 반환해요 | • 파일이 손상되지 않았는지 확인해주세요 • 파일을 다시 저장하거나 다시 내보내 보세요 |
| 429 | too_many_requests | 단위 시간당 한도(RPM·TPM·PPM) 중 하나를 초과함. 요청 수뿐 아니라 토큰 수·페이지 수 초과도 포함돼요 | • 응답 헤더 X-Upstage-RateLimit-Retry-After-*(-Requests·-Tokens·-Pages)로 어떤 rate limit을 초과했는지 확인해주세요. 초과한 항목에만 이 헤더가 포함돼요 • 헤더 값(Unix 타임스탬프, 초 단위)이 나타내는 시각 이후에 재시도하고, 단위 시간당 보내는 요청 수·토큰 수·페이지 수를 줄여주세요 • 한도 상향을 원하시면 상향 방법과 조건을 확인해주세요 |
| 429 | usage_limit_exceeded | 조직에 설정된 월간 후불 청구 금액 한도에 도달했어요. 크레딧으로 차감된 사용금액은 한도 계산에 포함되지 않아요. 요청 속도 제한이 아니므로 단순 재시도로는 해결되지 않아요. | • 크레딧을 충전해 이용하거나, 조직 Owner 권한으로 해당 조직의 결제 페이지에서 월간 후불 청구 금액 한도를 상향해주세요. |
| 499 | client_closed_request | 응답이 끝나기 전에 클라이언트가 연결을 끊음. 클라이언트 측 타임아웃이나 요청 취소가 원인이에요 | • HTTP 클라이언트의 타임아웃을 늘려주세요 • 스트리밍을 사용하면 첫 토큰을 더 빨리 받을 수 있어요 • 클라이언트와 API 사이의 프록시나 로드밸런서가 연결을 끊고 있지 않은지 확인해주세요 |
| 500 | internal_server_error / unknown_error | 요청 처리 중 오류가 발생 | • 잠시 후 다시 시도해주세요 • 진행 중인 서비스 장애가 있는지 status.upstage.ai에서 확인해주세요 • 계속 같은 에러가 발생하면 지원팀에 문의해주세요 |
| 503 | studio_subscription_gate_unavailable | 이 요청의 스튜디오 구독 사용량 상태를 읽지 못함. 쿼터를 다 썼다는 뜻은 아님 | • 잠시 후 다시 시도해주세요 • 계속 같은 에러가 발생하면 지원팀에 문의해주세요 |
| 503 | doorun_runtime_unavailable | 파일 컬렉션 가져오기를 처리할 작업 런타임을 일시적으로 사용할 수 없음. 가져오기는 시작되지 않음 | • 같은 Idempotency-Key 로 재시도하면 새 작업을 만들지 않고 기존 작업을 이어받습니다 • 응답에 Retry-After 헤더가 있으면 그 초만큼 기다린 뒤 재시도해주세요 • status.upstage.ai 에서 진행 중인 장애가 있는지 확인해주세요 |
| 502 / 503 | — | API 처리 전후의 인프라 계층에서 요청이 실패함 | • 잠시 후 다시 시도해주세요 • 진행 중인 서비스 장애가 있는지 status.upstage.ai에서 확인해주세요 |
| 504 | gateway_timeout | 게이트웨이 타임아웃 안에 요청이 완료되지 않음 | • 잠시 후 다시 시도해주세요 • 페이지 수나 프롬프트 길이 등 요청 크기를 줄여주세요 • 계속 같은 에러가 발생하면 지원팀에 문의해주세요 |