API 키 오류 해결

API 키가 안 될 때: 401·402·403·429 오류 원인과 해결

AI API 키가 작동하지 않는 이유를 정리했습니다. 401·402·403·429의 의미, 제공업체별 잔액 부족 오류 코드, 오류마다의 해결 방법을 안내합니다.

수정일
  • AI API 키(API key)가 "안 될 때"는 오류 번호가 이유를 알려 줍니다. 401은 키 자체가 잘못됐다는 뜻, 402는 대개 잔액이나 크레딧이 바닥났다는 뜻, 403은 그 키로는 해당 요청이 허용되지 않는다는 뜻, 429는 요청이 너무 많거나 일부 제공업체에서는 잔액이 없다는 뜻입니다.
  • 잔액 부족을 알리는 코드는 제공업체마다 다릅니다. DeepSeek, OpenRouter, Mistral, Together, Fireworks와 Gemini 선불 결제는 402, OpenAI·Kimi·Z.ai는 429, Alibaba Cloud의 Qwen은 403을 씁니다. 번호만 보지 말고 메시지를 읽으세요.
  • 잔액 오류는 기다려도 사라지지 않고, 속도 제한은 대개 기다리면 풀립니다. 아래 표에 2026년 11월 18일에 확인한 제공업체별 공식 오류 페이지를 정리했습니다.
iPhone용 Oriveo의 제공업체 화면. 연결한 제공업체와 이번 달 지출이 표시됩니다.

"API 키가 안 된다"는 정확히 무슨 뜻인가요?

API 키는 앱이 요청할 때마다 함께 보내는 비밀 코드로, AI 제공업체는 이 키를 보고 요청한 사람이 누구인지, 어느 계정에 요금을 매길지 압니다. 문제가 생기면 제공업체는 오류로 응답합니다. HTTP 상태 코드라는 세 자리 숫자와 짧은 메시지입니다.

숫자는 문제의 종류를, 메시지는 자세한 내용을 알려 줍니다. Oriveo는 흔한 오류를 "잘못된 API 키"나 "제공업체 할당량 소진" 같은 쉬운 제목으로 바꿔 보여 주며, 각각의 뜻은 이 페이지 아래쪽에서 설명합니다.

한눈에 보기: 401, 402, 403, 429, 5xx

여기서 시작하세요. 내 오류 번호를 찾은 뒤 아래의 해당 항목을 읽으면 됩니다. 이 요약은 2026년 11월 18일 기준 OpenAI, Anthropic 등 제공업체의 오류 페이지를 따릅니다.

한눈에 보기: 401, 402, 403, 429, 5xx
코드주된 의미기다리면 해결되나요?해결 방법
401키가 잘못되었습니다. 글자 누락, 앞뒤 공백, 삭제된 키, 다른 제공업체나 다른 지역의 키 등아니요키를 다시 복사하거나 새로 만들고, 제공업체와 지역을 확인합니다
402결제가 필요합니다. 선불 잔액이나 크레딧이 바닥났거나 결제에 문제가 있습니다아니요충전하거나 제공업체 결제 페이지에서 결제 수단을 고칩니다
403키는 맞지만 허용되지 않습니다. 지원하지 않는 국가·지역, 해당 모델 접근 권한 없음, 인증 절차 필요 등아니요지원 지역, 키 권한, 필요한 인증을 확인합니다
404모델 이름이나 주소가 잘못되었습니다아니요다른 모델을 고르거나 주소를 확인합니다
429짧은 시간에 요청이 너무 많거나, 일부 제공업체에서는 잔액 없음 또는 지출 한도 도달속도 제한이라면 대개 해결됩니다기다렸다가 다시 시도합니다. 메시지에 quota, balance, credit, spend limit이 있으면 충전하거나 한도를 올립니다
500–504, 529제공업체 쪽 장애나 과부하대개 해결됩니다나중에 다시 시도하거나 모델을 바꿉니다

잔액 부족(insufficient balance)이나 할당량(quota) 오류가 나는 이유는?

대부분의 제공업체는 선불 크레딧이나 유효한 결제 수단이 있어야 API가 작동하며, 잔액이 바닥났다는 사실을 알리는 방식은 제공업체마다 다릅니다. 이런 경우는 새 키로 해결되지 않고, 크레딧을 충전해야 해결됩니다.

아래는 Oriveo에 기본 탑재된 제공업체 15곳이 잔액이나 크레딧이 바닥났을 때 쓴다고 문서에 밝힌 코드입니다. "명시 안 됨"은 2026년 11월 18일에 확인한 제공업체 문서에 이 경우의 HTTP 코드가 나와 있지 않다는 뜻입니다.

잔액 부족(insufficient balance)이나 할당량(quota) 오류가 나는 이유는?
제공업체잔액 소진 시 코드메시지 내용공식 페이지
OpenAI429credit_balance_exhausted(오류 유형은 여전히 insufficient_quota로 표시될 수 있음)developers.openai.com/api/docs/guides/error-codes
Anthropic (Claude)명시 안 됨"Your credit balance is too low to access the Anthropic API". 결제 문제는 402 billing_error 반환platform.claude.com/docs/en/api/errors(코드), platform.claude.com/docs/en/about-claude/api-credits-for-subscribers(메시지)
Google Gemini402(선불 결제)payment_required. Cloud Billing에 미납 잔액이 있을 때도 403이 날 수 있음aistudio.google.com/docs/api-errors
OpenRouter402계정이나 API 키의 크레딧 부족openrouter.ai/docs/api-reference/errors
DeepSeek402Insufficient Balanceapi-docs.deepseek.com/quick_start/error_codes
xAI (Grok)명시 안 됨선불 크레딧이 바닥나면 요청이 거부됨docs.x.ai/console/billing
Mistral AI402Payment requireddocs.mistral.ai/resources/error-glossary
Groq문서에 없음Groq은 사용 후 청구하며, 오류 페이지에 잔액 오류가 없음console.groq.com/docs/errors
Together AI402Payment Requireddocs.together.ai/docs/error-codes
Fireworks AI402Payment Requireddocs.fireworks.ai/guides/inference-error-codes
MiniMax명시 안 됨(비즈니스 코드 1008)insufficient balanceplatform.minimax.io/docs/api-reference/errorcode
Z.ai (GLM)429(코드 1113)Insufficient balance or no resource package. Please recharge.docs.z.ai/api-reference/api-code
Qwen (Alibaba Cloud)403Arrearage 또는 isv.OUT_OF_SERVICE(계정 미납)alibabacloud.com/help/en/model-studio/error-code
Kimi (Moonshot AI)429exceeded_current_quota_errorplatform.kimi.ai/docs/api/errors
SiliconFlow문서에 없음잔액 오류가 나와 있지 않음docs.siliconflow.com/en/faqs/error-code

401: 잘못된 API 키 또는 인증 실패

401은 제공업체가 키를 알아보지 못한다는 뜻입니다. 대표적인 메시지는 "Incorrect API key provided"(OpenAI), "authentication_error"(Anthropic), "Authentication Fails"(DeepSeek), "Invalid API key: this is not an OpenRouter API key"(OpenRouter)입니다.

  • 제공업체 사이트에서 키를 다시 복사하고, 빠진 글자나 앞뒤 공백이 없는지 확인합니다.
  • 키가 선택한 제공업체의 것인지 확인합니다. OpenAI 키는 OpenRouter 키로 쓸 수 없고, 그 반대도 마찬가지입니다.
  • Kimi, MiniMax, Qwen은 지역별로 플랫폼이 따로 있어서 한 지역의 키는 다른 지역에서 작동하지 않습니다. Oriveo에서는 "공식 Endpoint" 선택기(Android: "공식 endpoint", iPhone: "공식 요청 URL")에서 맞는 지역을 고르세요.
  • 키가 삭제·폐기되었거나 만료되었다면 새로 만드세요.

402: 결제 필요 또는 잔액 부족

402는 돈 문제입니다. 선불 잔액이 비었거나 결제 수단에 문제가 생겼습니다. 제공업체 결제 페이지에서 충전하거나 결제 정보를 고친 뒤 다시 보내세요. 기다려도 해결되지 않습니다.

Oriveo에서는 "제공업체 할당량 소진"으로 표시되며, "이 API 키의 할당량 또는 잔액이 모두 소진되었다고 제공업체가 알렸습니다. 제공업체 콘솔에서 결제 정보를 확인하거나 모델을 변경하세요."라는 설명이 함께 나옵니다.

403: 접근 거부 또는 권한 없음

403은 제공업체가 키는 알아보지만 요청을 허용하지 않는다는 뜻입니다. 이유는 제공업체마다 다릅니다.

  • OpenAI는 지원하지 않는 국가에서 API를 쓰면 "Country, region, or territory not supported"를 반환합니다. 지원 국가 목록은 제공업체마다 공개되어 있습니다.
  • Gemini는 무료 티어 프로젝트에 인증이 필요할 때(FREE_TIER_VERIFICATION_REQUIRED), 연결된 Cloud Billing 계정에 미납 잔액이 있을 때, 유출 신고된 키를 Google이 차단했을 때 403을 반환합니다.
  • Anthropic은 키가 해당 리소스를 쓸 수 없을 때 permission_error를 반환합니다. 조직(organization)과 워크스페이스 설정을 확인하세요.
  • OpenRouter는 권한, 모더레이션, 가드레일, 예산 한도에 요청이 막히면 403을 반환합니다.
  • SiliconFlow는 일부 모델에 본인 인증을 요구합니다.
  • Qwen은 계정이 미납 상태일 때, 그리고 무료 할당량을 다 쓴 상태에서 "Free Quota Only" 설정이 켜져 있을 때(AllocationQuota.FreeTierOnly) 403을 씁니다.

429: 요청 과다, 속도 제한, 할당량 초과

429는 대부분 짧은 시간에 요청이나 토큰을 너무 많이 보냈다는 뜻입니다. 이것이 속도 제한(rate limit)이며, 수십 초 정도 기다리면 풀립니다. 응답에 Retry-After 시간이 있다면 그만큼 기다리세요.

몇몇 제공업체는 잔액 소진이나 지출 한도 도달에도 429를 쓰며, 이 경우는 기다려도 해결되지 않습니다. OpenAI(credit_balance_exhausted 또는 직접 정한 지출 한도), Kimi(exceeded_current_quota_error), Z.ai(코드 1113), 그리고 조직이 월 지출 한도에 도달한 Anthropic(enforced_spend_limit_reached)이 그렇습니다. Anthropic의 경우 더 높은 등급을 요청하지 않으면 다음 달까지 이어집니다.

무료 티어는 한도가 더 엄격합니다. Gemini 무료 티어와 OpenRouter 무료 모델에는 분당·일일 한도가 있습니다.

Oriveo에서 속도 제한은 웹에서 "속도 제한", iPhone과 Android에서 "제공업체 요청 제한"으로 표시됩니다. 메시지에 quota나 credit이 들어 있으면 대신 "제공업체 할당량 소진"으로 표시됩니다.

Oriveo 오류 메시지는 무슨 뜻인가요?

Oriveo에서 볼 수 있는 메시지를 한국어 화면 기준으로 정리했습니다.

Oriveo 오류 메시지는 무슨 뜻인가요?
Oriveo 표시의미해결 방법
저장했지만 키가 유효하지 않은 것 같습니다. 나중에 제공업체 설정에서 확인할 수 있습니다.Oriveo는 제공업체를 저장했지만, 확인 과정에서 제공업체가 키를 거부했습니다키를 다시 복사해 해당 제공업체 설정에서 고칩니다
잘못된 API 키(웹: 잘못된 API Key)제공업체가 401 또는 403을 반환했습니다키를 확인하거나 교체합니다. 403이라면 지역과 권한을 확인합니다
제공업체 할당량 소진제공업체가 이 키의 크레딧이나 할당량이 소진되었다고 알렸습니다(402, 또는 quota가 언급된 429)제공업체에서 충전하거나 다른 모델로 바꿉니다
속도 제한 / 제공업체 요청 제한지금은 요청이 너무 많습니다(429)잠시 기다렸다가 다시 시도합니다
무료 할당량 소진(Android: 무료 사용량 한도 도달)오늘의 Oriveo Free 사용량을 다 썼습니다. 내 API 키와는 관계없습니다내 API 키를 추가하거나 00:00 UTC 초기화를 기다립니다
OpenAI, Z.ai, Groq, Gemini, Anthropic 등 연결된 제공업체와 각각의 지출이 표시된 Oriveo 제공업체 화면
이 목록에서 제공업체를 열어 키를 확인하거나 교체합니다.

사용자 지정 엔드포인트, 릴레이, 게이트웨이를 쓰고 있다면?

사용자 지정 엔드포인트로 연결했다면 오류는 그 서비스에서 왔을 수도, 그 뒤에 있는 제공업체에서 왔을 수도 있습니다. Oriveo에 "이 연결이 상위 제공업체에 접속하지 못했습니다"라고 나오면, 그 서비스가 제공업체에 가진 계정이 유효하지 않거나, 크레딧이 없거나, 속도 제한에 걸렸을 수 있습니다. 내 설정 문제가 아니니 다른 연결로 바꾸거나 서비스 운영자에게 문의하세요.

새 키를 만들기 전에 확인할 것

새 키로 해결되는 것은 401 정도이고, 나머지는 대부분 해결되지 않습니다. 먼저 다음을 확인하세요.

  • 올바른 제공업체를 골랐는지, Kimi, MiniMax, Qwen, SiliconFlow, Z.ai라면 지역도 맞는지
  • 키 전체를 공백 없이 복사했는지
  • 계정에 크레딧이 있거나 유효한 결제 수단이 등록되어 있는지
  • 내 국가나 지역이 제공업체의 지원 목록에 있는지
  • 고른 모델을 내 계정이나 등급에서 쓸 수 있는지

앱 이용 중 자주 묻는 질문

API 키가 작동하지 않는 이유는 무엇인가요?
오류 번호를 보세요. 401은 키가 잘못됐다는 뜻, 402는 잔액이나 크레딧이 바닥났다는 뜻, 403은 요청이 허용되지 않는다는 뜻(대개 지역이나 권한 문제), 429는 요청이 너무 많거나 일부 제공업체에서는 잔액이 없다는 뜻입니다.
API 키 401 오류는 무슨 뜻인가요?
제공업체가 키를 알아보지 못한다는 뜻입니다. 공백 없이 다시 복사하고, 선택한 제공업체와 지역의 키인지 확인하거나, 새 키를 만드세요.
402 Payment Required 오류는 무엇인가요?
선불 잔액이나 크레딧이 바닥났거나 결제에 문제가 있다는 뜻입니다. DeepSeek, OpenRouter, Mistral, Together, Fireworks와 Gemini 선불 결제가 이 코드를 씁니다. 제공업체 결제 페이지에서 충전하세요. 기다려도 해결되지 않습니다.
429 오류는 속도 제한인가요, 할당량 문제인가요?
둘 다일 수 있습니다. 대개는 잠시 기다리면 풀리는 속도 제한입니다. 하지만 OpenAI, Kimi, Z.ai는 잔액이 없을 때도 429를 반환하므로, 메시지에 quota, balance, credit이 있으면 기다리지 말고 크레딧을 충전하세요.
OpenAI API 키에 insufficient_quota가 뜨는 이유는 무엇인가요?
OpenAI API 계정에 선불 크레딧이 남아 있지 않기 때문입니다. OpenAI는 credit_balance_exhausted 코드와 함께 429를 반환하며, 오류 유형은 여전히 insufficient_quota로 표시될 수 있습니다. OpenAI 결제 설정에서 크레딧을 충전하세요. 새 키는 도움이 되지 않습니다.
새 API 키를 제대로 복사했는데도 안 되는 이유는 무엇인가요?
대개 계정에 아직 크레딧이 없거나 결제가 설정되지 않았거나, 키가 다른 지역의 것이거나, 내 국가에서 API가 제공되지 않기 때문입니다. 키를 또 만들기 전에 이것부터 확인하세요.

함께 읽기

블로그 글

어떤 키든 오류 이유를 쉬운 말로

웹 앱을 열거나 iPhone·Android용 Oriveo를 내려받아 제공업체 15곳의 키를 추가하세요. 요청이 실패하면 이유를 분명하게 알려 줍니다.

API 키가 아직 없어도 Oriveo Free로 시작할 수 있습니다.