OpenAI API quota exceeded 오류: 잔액·지출 한도 확인과 복구

OpenAI API의 quota exceeded는 ‘사용할 수 있는 할당량을 초과했다’는 뜻입니다. 첫 호출부터 You exceeded your current quota 또는 insufficient_quota가 나와도 요청을 너무 많이 보냈다는 의미로 단정하면 안 됩니다. 선불 잔액 소진, 조직·프로젝트의 강제 지출 상한, OpenAI가 승인한 월간 사용 한도가 각각 원인일 수 있습니다.

먼저 자동 재시도를 멈추고 실패 응답의 error.code를 확인하세요. 잔액 문제는 크레딧 추가, 직접 설정한 지출 상한은 해당 설정 조정, 승인된 사용 한도는 증액 요청으로 대응합니다. 이 세 가지는 서로 대신할 수 없습니다. error.type은 여러 원인에서 공통으로 insufficient_quota일 수 있으므로, 이 값만 보고 무조건 충전하지 마세요. OpenAI 공식 오류 코드 안내

아래 절차는 OpenAI Platform에 직접 연결한 API를 기준으로 합니다. ChatGPT Plus·Pro 구독과 API 결제는 별개이므로 ChatGPT를 결제했다는 사실만으로 API 잔액이 생기지는 않습니다. ChatGPT와 API 결제 구분

insufficient_quota에서 먼저 읽을 오류 코드

터미널에 RateLimitError: 429만 보이면 응답 본문까지 확인합니다. 공식 Python SDK는 HTTP 429를 RateLimitError로 처리하므로, 예외 이름만으로 재시도하면 되는 오류인지 알 수 없습니다. 본문의 error.code, error.type, error.message를 함께 읽어야 합니다. 공식 오류 코드 및 SDK 예외 설명

이 표는 현재 공식 오류 코드 정의에 따른 구분입니다. 앞의 두 지출 상한은 직접 설정하는 제어이며, 마지막 승인 한도는 OpenAI가 부여하는 한도입니다. 잔액을 추가해도 이 한도들이 자동으로 늘어나지는 않습니다.

아래는 응답 구조를 설명하기 위해 만든 예시이며 실제 API 호출 결과가 아닙니다. 넓은 오류 분류와 구체적인 원인이 어떻게 함께 표시되는지 보세요.

{
  "error": {
    "type": "insufficient_quota",
    "code": "credit_balance_exhausted",
    "message": "The organization has no prepaid credits remaining."
  }
}

이 예시에서는 선불 잔액을 확인할 차례입니다. 반대로 project_spend_limit_exceeded가 나오면 충전 버튼보다 해당 프로젝트의 지출 상한을 먼저 봐야 합니다.

세부 코드가 없고 예전의 insufficient_quota 메시지만 남아 있다면 잔액이 0이라고 단정하지 않습니다. 원본 응답을 확보한 뒤 실제 요청의 조직·프로젝트를 맞추고, 그 조직의 잔액과 승인 한도, 적용 중인 강제 지출 상한을 확인하세요. 오류가 요청·토큰 속도 제한을 명시한다면 RPM·TPM 확인과 재시도 방법으로 넘어갑니다.

결제 화면과 실패한 요청이 같은 조직·프로젝트인지 확인하세요

계정 설정을 바꾸기 전에 실패한 요청이 어느 조직에 청구되는지부터 맞춰야 합니다. 여러 조직에 속해 있거나 로컬과 서버가 다른 키를 쓰면, 잔액이 남은 결제 화면을 보고도 다른 조직의 오류를 해결하려 할 수 있습니다.

1. 앱이나 자동화 도구의 API 접속 주소를 확인합니다. OpenAI에 직접 보내는지, 중간 제공자의 주소를 쓰는지 구분합니다.
2. 실패한 환경에서 선택한 API 키가 속한 조직과 프로젝트를 관리 화면에서 확인합니다. 키 문자열 전체를 로그에 출력할 필요는 없습니다.
3. 그 조직의 API Billing과 Organization limits를 엽니다. 프로젝트 오류라면 설정 화면에서 해당 프로젝트를 선택합니다.
4. 로컬 호출만 성공한다면 서버·배포 환경에 지정된 키의 소속과 접속 주소가 같은지 비교합니다. 성공한 로컬 요청이 다른 프로젝트를 썼다면 서버의 복구 증거가 되지 않습니다.

여러 조직에 속한 사용자나 이전 방식의 사용자 키를 쓰는 경우에는 OpenAI-Organization, OpenAI-Project 헤더로 대상을 지정할 수 있습니다. 다만 이 헤더로 프로젝트 전용 키를 다른 조직이나 프로젝트에 임의로 연결할 수는 없습니다. 키가 허용하는 범위 안에서 요청 대상과 결제 화면을 맞추는 용도입니다. 공식 API 인증 설명

LangChain이나 자동화 도구에서 오류를 받았다면 도구가 내 OpenAI 키를 사용하는 방식인지, 제공자의 계정으로 호출하는 방식인지도 확인하세요. 내 키라면 그 키의 Platform 설정이 확인 대상입니다. 제공자의 계정이라면 제공자에게 적용된 한도와 연결 설정을 확인해야 합니다. OpenAI와 비슷한 JSON 메시지만으로 내 OpenAI 잔액이 부족하다고 판단해서는 안 됩니다.

잔액 소진이면 카드 등록보다 실제 크레딧 반영을 확인합니다

credit_balance_exhausted는 조직에 남은 선불 크레딧이 없다는 뜻입니다. 해당 조직의 Billing에서 현재 잔액을 확인하고, API 결제를 관리할 수 있는 담당자가 필요한 크레딧을 추가해야 합니다. 조직의 API 결제 내역은 조직 소유자(owner)가 확인할 수 있으므로 화면을 볼 수 없다면 그 담당자에게 요청하세요. 잔액 소진 오류, API 결제 관리 권한

카드 등록, 결제 성공, 사용 가능한 크레딧 표시는 서로 다른 확인 단계입니다. 충전했다면 결제가 승인됐는지만 보지 말고 실제 요청에 쓰는 조직의 잔액이 증가했는지 확인합니다. 공식 선불 결제 안내는 구매한 잔액이 반영되기까지 몇 분이 걸릴 수 있다고 설명하지만, 모든 계정이 정확히 몇 분 뒤 복구된다는 보장은 하지 않습니다. 선불 API 결제 안내

충전액보다 잔액 증가분이 적다면 기존 음수 잔액도 확인하세요. 사용 중단과 사용량 집계가 즉시 처리되지 않아 음수 잔액이 발생할 수 있으며, 다음 구매액에서 그 금액이 차감됩니다. 구매한 크레딧은 1년 후 만료되므로 과거에 충전한 기록이 있다고 해서 현재 잔액이 남아 있다고 볼 수도 없습니다. 무료 크레딧이 실제 계정에 남아 있으면 먼저 사용되지만, 새 계정에 무료 크레딧이 반드시 지급되는 것은 아닙니다. 선불 잔액·만료·차감 규칙

자동 충전을 설정했더라도 월간 자동 구매 상한과 API 지출 상한을 혼동하지 마세요. 자동 구매 상한은 자동 충전으로 살 수 있는 크레딧 금액을 제한합니다. 수동 구매는 그 자동 구매 상한에 포함되지 않지만, 크레딧을 수동으로 추가해도 API에 걸린 강제 지출 상한이나 승인된 사용 한도가 해제되는 것은 아닙니다. 잔액이 반영되면 원래 요청의 오류 코드를 다시 확인해 다음 조치를 결정합니다. 자동 충전 설정 설명

예산 알림과 호출을 막는 강제 지출 상한은 다릅니다

관리 화면에 월간 예산 금액이 보인다는 이유만으로 그 금액이 API를 막는다고 판단하지 마세요. 지출 알림(spend alert)은 통지만 하고 호출을 계속 허용합니다. 해당 지출 한도에서 Enforce a hard limit을 켠 경우에 한도 도달이 요청 실패로 이어집니다. 공식 지출 한도 안내

조직 또는 프로젝트의 지출 상한 오류가 나왔다면, 설정을 관리할 권한이 있는 담당자가 다음 순서로 확인합니다.

• 조직 오류: Organization limits의 Spend → Edit spend limit에서 Monthly spend limit과 Enforce a hard limit을 확인합니다.
• 프로젝트 오류: 프로젝트 설정에서 해당 프로젝트를 선택한 뒤 Limits → Spend → Edit spend limit에서 같은 항목을 확인합니다.
• 현재 사용액과 오류가 가리키는 상한을 비교합니다. 비용을 감당할 수 있고 업무를 재개해야 한다면 승인된 범위에서 상한을 높이거나 해제하고 Save로 저장합니다. 예산을 유지해야 한다면 사용을 보류하고 다음 월간 주기 초기화를 기다립니다.

조직 상한은 조직 안의 모든 프로젝트에 적용됩니다. 프로젝트 상한은 해당 프로젝트에만 적용되므로, 다른 프로젝트가 성공해도 실패한 프로젝트의 상한이 풀렸다고 볼 수 없습니다. 또한 프로젝트 상한만 높여도 조직 상한에 걸려 있으면 계속 실패할 수 있습니다. 변경 사항은 반영 시간이 필요하며 집계된 사용액이 설정 금액을 조금 넘을 수 있으므로, hard limit을 즉시 작동하는 정확한 비용 차단 장치로 생각해서도 안 됩니다. 상한 적용 범위와 복구 조건

예를 들어 설명을 위한 가정으로, 선불 잔액이 20달러(USD) 남아 있어도 해당 프로젝트가 강제 월간 상한 10달러(USD)를 이미 모두 사용했다면 프로젝트 요청은 막힐 수 있습니다. 10달러를 더 충전하면 잔액은 늘지만 프로젝트 상한은 그대로입니다. 이때 조정할 대상은 충전액이 아니라 오류에 표시된 강제 지출 상한입니다.

승인된 월간 사용 한도라면 증액 절차가 필요합니다

organization_usage_limit_exceeded는 OpenAI가 조직에 부여한 월간 사용 한도에 도달했다는 뜻입니다. 이 한도는 사용자가 직접 설정한 조직·프로젝트 지출 상한과 별개입니다. 공식 오류 정의

조직 담당자는 Organization limits에서 현재 승인 한도를 확인하고, 제공되는 절차로 더 높은 승인 한도를 요청하거나 OpenAI 지원에 문의합니다. 여기서는 크레딧을 더 구매하거나 프로젝트의 자체 상한을 높이는 것만으로 복구됐다고 판단할 수 없습니다. 승인된 한도가 실제로 바뀌었는지 확인하고 원래 요청으로 다시 검증해야 합니다. 특정 증액 금액이나 승인 시간을 모든 계정에 보장할 수도 없습니다.

충전·한도 조정 후에는 같은 요청 경로로 복구를 확인하세요

잔액이나 상한이 화면에 반영됐다고 해서 원래 앱의 호출까지 복구된 것은 아닙니다. 다음은 이 글에서 실제 호출한 결과가 아니라, 권한 있는 사용자가 적용할 확인 절차입니다. 모델에 요청을 보내면 사용 요금이 발생할 수 있습니다.

1. 자동 재시도와 병렬 작업을 멈춘 상태에서, 원래 실패한 접속 주소·조직·프로젝트·키·모델을 그대로 사용합니다. 다른 모델이나 다른 프로젝트로 성공한 결과를 대신 쓰지 않습니다.
2. 기존 요청의 형식을 유지하되 입력을 짧게 하고 필요한 출력 상한을 정해 요청 하나만 보냅니다. 모델별 필수 입력은 유지해야 합니다.
3. 정상 응답과 실제 모델 결과가 돌아오는지 확인합니다. GET /v1/models의 모델 목록만 열리거나 키가 인증됐다는 사실은 유료 모델 요청의 복구를 증명하지 않습니다.
4. 성공했다면 그 설정의 단일 요청이 복구된 것입니다. 낮은 동시 실행 수로 업무를 재개하고 요청 수·토큰 수·오류율을 보며 늘립니다. 한 번의 성공으로 전체 운영 부하를 처리할 수 있다고 단정하지 않습니다.

실패했다면 이전과 세부 코드가 같은지부터 비교하세요.

응답에 openai-organization이 있으면 실제 조직 확인에 활용하고, x-request-id는 지원 문의용으로 보관합니다. 발생 시각과 시간대, 모델·엔드포인트, 조직·프로젝트, 오류 코드, 변경한 결제·한도 설정과 재확인 결과를 함께 정리하면 “충전했는데 안 된다”보다 구체적으로 설명할 수 있습니다. API 키와 인증 헤더, 민감한 사용자 입력은 공유하지 마세요. 공식 요청 추적·인증 안내

자주 묻는 질문

ChatGPT Plus나 Pro를 결제하면 API 할당량도 늘어나나요?

아니요. ChatGPT와 OpenAI API는 결제가 분리되어 있습니다. API는 사용하는 조직의 Platform Billing에서 별도로 결제 상태와 잔액을 확인해야 합니다. ChatGPT의 구독 영수증은 API 크레딧 충전 내역이 아닙니다. 공식 결제 구분

API 키를 처음 만들었는데 왜 바로 quota exceeded가 나오나요?

키 발급은 호출을 인증할 수단을 만든 것이며, 사용 가능한 크레딧이나 지출·사용 한도를 보장하지 않습니다. 세부 오류 코드와 그 키가 속한 조직의 잔액·한도를 확인하세요. 같은 프로젝트에서 새 키를 만들어도 소진된 잔액이나 도달한 상한은 그대로입니다. API 인증 설명, 결제 관련 오류 코드

insufficient_quota면 무조건 잔액이 0이라는 뜻인가요?

아니요. insufficient_quota는 넓은 오류 분류이며, error.code에는 선불 잔액 소진뿐 아니라 조직·프로젝트의 강제 지출 상한이나 승인된 사용 한도 초과가 표시될 수 있습니다. 세부 코드가 없다면 잔액을 추정하지 말고 원본 응답과 해당 조직의 설정을 확인해야 합니다. 공식 오류 코드 안내

충전한 뒤 몇 분 기다리면 해결되나요?

모든 계정에 적용되는 고정 대기 시간은 없습니다. 공식 선불 결제 안내는 구매 잔액 반영에 몇 분이 걸릴 수 있다고 설명합니다. 실제 잔액이 반영됐는지 확인한 뒤 같은 조직·프로젝트·모델로 요청 하나를 보내세요. 계속 실패하면 세부 오류 코드를 다시 읽고, 다른 상한이나 잘못된 요청 대상이 원인인지 확인해야 합니다. 선불 결제 반영 안내