OpenAI API 429 오류 해결: 잔액·지출 한도·RPM·TPM 확인 순서

OpenAI API의 429는 요청을 너무 많이 보냈을 때만 나오는 오류가 아닙니다. 크레딧 소진이나 월간 지출 한도 때문에 첫 호출부터 실패할 수도 있습니다. 먼저 실패 응답의 error.code, error.type, error.message를 확인하세요. 결제 문제라면 계정 설정을 바꿔야 하고, 일시적인 요청 제한이라면 대기 시간과 호출량을 조절해야 합니다. 같은 429라도 필요한 조치가 다릅니다.

이 글은 OpenAI Platform에 직접 보내는 API 요청을 기준으로 하며, 오류 분류와 공개 모델 한도는 2026년 9월 8일 공식 문서를 확인했습니다. Azure OpenAI를 사용한다면 Azure의 TPM 할당과 배포별 한도를 확인하세요. 다른 제공자를 거치는 요청은 그 제공자의 오류 응답과 결제 기준을 함께 확인해야 합니다.

지금 실패한 요청에서 먼저 볼 것

자동 재시도나 병렬 작업을 잠시 멈추고 실제로 실패한 요청 하나의 응답 본문을 확보합니다. 터미널에 RateLimitError라는 예외 이름만 표시된다면 세부 메시지와 응답 본문까지 펼쳐 보세요. Python SDK는 서로 다른 원인의 HTTP 429를 모두 RateLimitError로 분류하므로 예외 이름만으로 충전이 필요한지 판단할 수 없습니다. Python SDK 오류 처리 문서

다음 표에서 응답과 일치하는 항목을 찾으면 첫 조치를 결정할 수 있습니다. 세부 코드가 없을 때는 type과 메시지를 함께 읽고, 모르는 코드를 일시적인 제한으로 단정하지 마세요. OpenAI 한국어 429 해결 안내

예를 들어 아래는 프로젝트의 지출 상한을 확인해야 하는 응답 형태입니다. 실제 API 호출 결과가 아닌 설명용 예시입니다.

{
  "error": {
    "message": "The project monthly spend limit has been exceeded.",
    "type": "insufficient_quota",
    "code": "project_spend_limit_exceeded"
  }
}

이 경우 1초마다 다시 보내거나 새 키를 발급해도 지출 상한은 그대로입니다. 반대로 토큰 제한 메시지가 나왔다면 크레딧을 더 충전하는 것만으로 해당 TPM 문제가 해결되지는 않습니다.

카드를 등록했는데도 429가 나오는 이유

먼저 지금 확인하는 결제 화면과 실패한 API 키가 같은 조직·프로젝트를 가리키는지 맞춰 보세요. 로컬에서는 호출되지만 서버에서만 실패한다면 배포 환경이 이전 키를 계속 사용하고 있거나, 다른 프로젝트 설정이 적용됐을 가능성을 점검할 수 있습니다. 키 원문을 로그에 출력하지 말고, 설정에 지정한 조직·프로젝트와 해당 키의 소속을 관리 화면에서 확인합니다.

카드 등록, 선불 크레딧, 월간 사용 한도는 각각 확인할 항목입니다. 카드가 등록되어 있다는 사실만으로 사용 가능한 크레딧이나 충분한 지출 상한이 보장되지는 않습니다.

자동 충전을 켜 두었는데 크레딧이 소진됐다면 OpenAI API 자동 충전 실패 시 잔액 복구와 정상 작동 확인 방법을 확인하세요. 수동 충전으로 호출을 복구하는 절차와 이후 자동 충전이 정상인지 확인하는 절차를 구분해 안내합니다.

insufficient_quota가 나온다면 다음 순서로 확인하세요.

1. 실패한 키가 속한 조직의 사용 가능한 크레딧을 확인합니다. 크레딧 소진 코드라면 필요한 결제 조치부터 처리합니다.
2. 조직에 승인된 월간 사용 한도를 확인합니다. 선불 잔액을 추가하는 일과 승인된 한도를 늘리는 일은 별개입니다.
3. 조직과 프로젝트의 월간 지출 상한을 확인합니다. 조직 상한은 조직 전체 프로젝트에 영향을 주며, 프로젝트 상한은 해당 프로젝트에 적용됩니다.
4. 변경 사항이 적용될 시간을 둔 뒤 같은 키·프로젝트·모델로 작은 요청 하나를 보냅니다.

관리 화면의 모든 예산 항목이 호출을 막는 상한은 아닙니다. 알림용 예산은 통지만 하고, 강제 지출 상한은 호출을 차단합니다. 오류가 지출 상한을 명시했다면 해당 상한을 확인해야 합니다. 월간 상한은 다음 사용 기간이 시작되면 다시 사용할 수 있지만, 설정 변경이 즉시 반영된다고 가정해서는 안 됩니다. OpenAI 지출 한도 문서

한국어 개발 사례에서도 첫 호출 실패 후 만료된 크레딧을 확인하고 충전한 경험을 볼 수 있습니다. 다만 이는 2024년 개인 사례이며, 현재 모든 계정에 무료 크레딧이 있거나 특정 최소 결제액으로 해결된다는 근거는 아닙니다. 자신의 오류 코드와 결제 상태를 기준으로 판단해야 합니다.

잔액은 충분한데 insufficient_quota가 반복된다면 같은 확인을 계속하기보다 OpenAI API 할당량 초과 오류의 계정별 점검 방법으로 범위를 좁힐 수 있습니다.

요청 제한이면 RPM과 TPM을 따로 확인한다

RPM은 분당 요청 수, TPM은 분당 토큰 수입니다. 한 요청의 입력 문서가 길거나 출력 상한이 크면 호출 횟수가 적어도 토큰 제한에 먼저 도달할 수 있습니다. 또 한도를 분당 숫자로 표시하더라도 더 짧은 구간의 급격한 요청 집중으로 제한될 수 있어, 1분 평균이 낮다는 이유만으로 여유가 있다고 판단하면 안 됩니다. 공식 요청 한도 가이드

OpenAI Platform의 Limits에서 실제 조직·프로젝트·모델 값을 확인한 다음, 실패 전후 응답 헤더를 비교하세요. 한도는 조직과 프로젝트에 적용되며, 모델별로 다르거나 여러 모델이 공유할 수 있습니다. 공개된 사용 등급 표는 참고 기준이고 현재 계정에 표시되는 값이 운영 판단의 기준입니다.

응답에 프로젝트 토큰 한도 관련 x-ratelimit-* 헤더가 있다면 함께 기록합니다. 헤더가 없다는 것은 해당 응답에서 값을 얻지 못했다는 뜻이지, 한도가 없다는 뜻이 아닙니다. SDK나 중간 서버가 전달하지 않는 경우도 확인해야 합니다.

남은 요청 수가 먼저 줄어들면 작업 큐에서 요청을 고르게 내보내고 동시 실행 수를 줄입니다. 남은 토큰이 먼저 줄어들면 중복된 대화 기록, 긴 입력 문서, 불필요하게 큰 출력 상한을 점검합니다. Responses API에서는 max_output_tokens, Chat Completions에서는 max_completion_tokens를 사용하며, 추론 모델에서는 추론 토큰과 사용자에게 보이는 출력이 이 예산에 포함됩니다. 출력값을 줄일 때는 답변을 완성할 만큼의 여유도 남겨야 합니다. OpenAI 429 해결 안내

두 잔량이 남아 있어도 slow_down이면 트래픽 증가 속도를 낮춰야 합니다. 서버를 늘리거나 배포 직후 작업자를 한꺼번에 시작하는 상황에서는 낮은 동시 실행 수로 재개한 뒤 단계적으로 늘리는 편이 적절합니다.

재시도가 장애를 키우지 않게 하려면

재시도는 일시적인 제한으로 확인된 요청에만 적용합니다. 결제·사용 한도 오류나 정체를 모르는 429를 무조건 반복하면 복구 여부를 알기 어려워집니다. 실패한 요청도 한도 계산에 포함되므로 즉시 반복 호출하면 제한이 더 오래 이어질 수 있습니다. OpenAI 요청 한도 가이드

재시도 정책에는 다음 조건을 함께 넣으세요.

• 유효한 Retry-After가 있으면 그 시간이 지나기 전에 다시 보내지 않습니다. 초 단위 값과 HTTP 날짜 형식을 처리합니다.
• 헤더가 없거나 유효하지 않으면 무작위 지연을 섞은 지수 백오프를 사용합니다. 여러 작업자가 같은 순간에 재시도하는 일을 줄이기 위한 조치입니다.
• 최대 시도 횟수와 전체 대기 시간에 한도를 둡니다. 서버의 대기 시간이 남은 처리 예산보다 길면 작업을 보류하거나 종료합니다. 대기 시간을 임의로 줄여 먼저 재시도하지 않습니다.
• SDK와 작업 큐의 재시도를 합산합니다. 어느 한 곳에서 전체 재시도 횟수를 관리하도록 설계합니다.

Python SDK는 재시도 대상 오류에 기본적으로 두 번 재시도하며, max_retries=0으로 끌 수 있습니다. 직접 재시도 정책을 구현한다면 SDK 기본값을 그대로 둔 채 중첩하지 않도록 확인하세요. APIStatusError에서 request_id와 응답 정보를 얻을 수 있습니다. 이 글에서는 SDK 설치나 실제 API 호출을 수행하지 않았습니다. Python SDK 참조 문서

예를 들어 작업자가 총 세 번 시도하고 매번 SDK가 최초 호출에 더해 두 번 재시도하면, 한 작업이 최대 아홉 번의 요청으로 늘어날 수 있습니다. 동시 작업자 20개가 같은 정책을 실행하면 대기 중인 작업을 다시 한꺼번에 밀어 넣게 됩니다. 재시도 횟수를 줄이는 것과 새 요청 유입을 제한하는 일을 함께 적용해야 합니다.

HTTP 503의 server_is_overloaded는 별도로 다룹니다. type: service_unavailable_error이며 모델의 일시적인 처리 용량 부족을 뜻합니다. 계정 크레딧 소진으로 해석해 충전할 문제가 아닙니다. 재시도 안내를 따르고, 지속되면 OpenAI 상태 페이지를 확인하세요. 대체 모델을 사용할 때도 품질·비용 차이와 한도 공유 여부를 미리 점검해야 합니다. 공식 오류 코드 문서

복구 확인은 원래 설정으로 요청 하나부터

충전이나 지출 상한 변경 후 대규모 작업을 바로 재시작하면 설정 반영 여부와 새로운 요청 제한을 구분하기 어렵습니다. 다음 절차는 원인을 좁히기 위한 운영 방법입니다.

1. 원래 실패한 키·프로젝트·모델을 그대로 두고, 병렬 실행과 반복 재시도를 멈춥니다.
2. 입력을 짧게 하고 적절한 출력 상한을 정해 요청 하나만 보냅니다.
3. 성공하면 응답과 반환된 사용량·헤더를 기록합니다. 실패하면 이전 응답과 세부 코드가 같은지 비교합니다.
4. 낮은 동시 실행 수로 업무를 재개하고 요청 수, 토큰 수, 오류율을 보며 조금씩 늘립니다.

예컨대 credit_balance_exhausted가 사라지고 대량 작업에서만 토큰 제한 메시지가 나온다면, 결제 문제를 계속 만지기보다 처리량을 조절할 차례입니다. 같은 지출 한도 코드가 유지되면 설정한 조직·프로젝트가 맞는지와 변경 적용 여부를 다시 확인합니다. 모델을 바꾼 뒤 성공한 요청은 원래 모델이 복구됐다는 확인이 되지 않습니다.

지원 요청이 필요하면 발생 시각과 시간대, 요청 ID, 모델 ID, 엔드포인트, 조직·프로젝트 식별 정보, HTTP 상태, 오류 본문에서 필요한 필드와 제한 헤더를 정리하세요. API 키, 인증 헤더, 사용자 입력 전문은 공유하지 않습니다. “충전했지만 안 된다”보다 실패한 요청이 어느 계정 설정에 연결되고 어떤 코드를 반환했는지가 원인 파악에 도움이 됩니다.

GPT-6 Astra를 쓰는 경우의 처리량 계산

기존 서비스를 운영하거나 배치 작업을 계획한다면 복구 이후의 지속 처리량도 계산해야 합니다. 아래는 2026년 9월 8일 확인한 GPT-6 Astra 모델 페이지의 공개 사용 등급별 수치입니다. 특정 키에 이 값이 적용되거나 모델 접근이 허용된다는 보장은 아니므로 실제 Limits와 함께 사용하세요.

실시간 요청을 계획할 때는 다음 두 값 중 작은 쪽에서 출발합니다.

요청 수 기준: RPM
토큰 기준: TPM ÷ 요청당 계획 토큰 수
계획 처리량: 두 값 중 작은 값에 운영 여유를 반영

T2에서 요청당 계획 토큰 수를 5,000으로 잡으면 토큰 기준 계산은 1,000,000 ÷ 5,000 = 분당 200건입니다. RPM이 5,000이어도 같은 크기의 요청을 분당 5,000건 처리할 수 있다는 뜻은 아닙니다. 이는 실측 성능이 아닌 단순 용량 계산이며, 실제로는 큰 입력의 비중, 출력 상한, 순간 부하와 응답 헤더를 보며 조정해야 합니다.

Batch는 즉시 응답이 필요 없는 작업을 옮길 때 검토합니다. 표의 Batch 값은 해당 모델에 제출되어 아직 끝나지 않은 입력 토큰의 합계를 뜻합니다. 실시간 TPM에 더해 쓸 수 있는 토큰 잔액이나 일일 허용량이 아닙니다. T2에서 각 작업의 입력이 50,000토큰이라면 대기 입력 3,000,000토큰은 단순 계산으로 약 60개 작업에 해당합니다. 기존 대기 작업까지 포함해 계산하고, 작업이 완료되면 그 입력 토큰은 대기열 점유에서 빠집니다. Batch 한도 설명

Astra의 입력 272K 초과 구간에 적용되는 가격 규칙은 429 발생 임계값이 아닙니다. 긴 입력의 비용은 GPT-6 Astra API 요금 안내에서 별도로 확인할 수 있습니다. 또한 같은 모델의 Standard와 Fast는 요청 한도를 공유하므로 Fast 선택만으로 RPM이나 TPM이 늘어나지 않습니다. Fast 모드 한도 안내

한도 증액이 필요한 시점

짧은 요청 하나도 결제 관련 코드로 실패한다면 먼저 계정 문제를 해결해야 합니다. 평소에는 정상인데 배포나 배치 시작 시점에만 429가 몰린다면 큐와 동시 실행 수를 조정할 여지가 있습니다. 요청을 고르게 보내고 입력·출력 토큰을 줄인 뒤에도 지속 수요가 현재 RPM·TPM을 넘는다면 증액을 검토할 수 있습니다.

증액 검토에는 현재 한도, 시간대별 요청량·토큰량, 요청당 토큰 분포, 최대 동시 실행 수, 적용한 대기·큐 정책과 오류 기록을 준비하세요. 필요한 것이 지속 처리량인지, 잠깐의 집중 부하를 흡수할 대기열인지 구분할 수 있습니다.

Codex에서 exceeded retry limit가 보이는 경우에는 재시도 종료 메시지 앞에 나온 원래 API 오류부터 찾아야 합니다. 그 메시지만으로 잔액 소진과 호출 제한을 구분할 수는 없습니다. 도구 안에서 원인을 추적하는 과정은 Codex 429 재시도 한도 초과 해결을 참고하세요.