NNexithDocs
상태대시보드 ↗
개요 및 빠른 시작모델 카탈로그가이드API 레퍼런스연동OAuth2 / OIDC

오류와 속도 제한

적용 대상: 모든 /v1 엔드포인트


1. 오류 형식#

모든 비스트리밍 오류 응답 본문은 다음 형식으로 통일되어 있습니다:

{
  "error": {
    "message": "The model 'gpt-4o' does not exist.",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}
  • message는 사람이 읽는 값이며 안정성을 보장하지 않으므로 로직 판단에 사용하지 마세요.
  • code는 기계가 읽는 값이며 분기 처리에 사용합니다.
  • type은 대분류입니다(authentication_error / rate_limit_error / billing_error / invalid_request_error / server_error).

2. 오류 코드 표#

code HTTP 의미 처리 권장
missing_api_key 401 자격 증명 누락 Authorization: Bearer 추가
invalid_api_key 401 Key가 없거나 폐기됨 Key 교체
invalid_token 401 JWT 만료 또는 유효하지 않음 다시 로그인
unauthorized 401 기타 인증 실패 자격 증명 확인
forbidden 403 권한 없음(예: nx- Key로 /v1/images/edits 호출) JWT로 변경
invalid_request 400 파라미터가 유효하지 않음 message에 따라 수정
model_not_found 404 모델이 없거나 공개되지 않음 GET /v1/models로 확인
not_found 404 리소스가 없거나 현재 사용자 소유가 아님 ID 확인
conflict 409 유니크 충돌 조회 후 재시도
payload_too_large 413 요청 본문/파일 한도 초과 파일 축소(파일 ≤10MB, 전역 body ≤32MB)
rate_limit_exceeded 429 RPM 초과 Retry-After에 따라 백오프
token_rate_limit_exceeded 429 TPM 초과 Retry-After에 따라 백오프
quota_exceeded 429 플랜 월간 할당량 소진 플랜 업그레이드 또는 다음 달까지 대기
insufficient_balance 402 잔액 부족 충전 후 재시도
inference_unavailable 502 업스트림 사용 불가(장애 조치 시도 완료) 재시도 가능
model_overloaded 503 업스트림 과부하 재시도 가능
internal_error 500 서버 오류 재시도; 계속 실패하면 문의

업스트림의 실제 모델 이름, 공급자 URL, 원본 오류 텍스트는 응답에 나타나지 않습니다(불투명 원칙). 작업 관련 오류는 고정 문구만 반환합니다.


3. 속도 제한#

(API Key, 모델) 단위로 버킷을 나누고 1분 창을 사용합니다. 해석 순서:

  1. Key 수준 재정의(콘솔 설정)
  2. 모델 수준 기본값
  3. 플랜 기본값
  4. 시스템 폴백: 60 RPM / 40,000 TPM

429 응답 헤더#

Header 설명
X-RateLimit-Limit-Requests RPM 상한
X-RateLimit-Remaining-Requests 이번 분의 남은 요청 수(초과 시 0)
X-RateLimit-Reset 창 재설정 시각(Unix 초)
X-RateLimit-Limit-Tokens TPM 상한
X-RateLimit-Remaining-Tokens 이번 분의 남은 token(초과 시 0)
Retry-After 권장 대기 초

클라이언트 권장 사항#

import time, random
from openai import OpenAI, RateLimitError

def call_with_retry(fn, attempts=4):
    for i in range(attempts):
        try:
            return fn()
        except RateLimitError as e:
            wait = float(e.response.headers.get("Retry-After", 1))
            time.sleep(wait + random.uniform(0, 0.5))
    raise
  • 429 / 502 / 503 / 500에만 재시도하세요; 4xx 파라미터 오류는 재시도해도 의미가 없습니다.
  • 지수 백오프 + 지터를 사용하고 Retry-After를 존중하세요.
  • 이미지 작업은 비동기이므로 제출이 202를 반환해도 생성 완료를 의미하지 않습니다. 재제출 시 idempotency_key를 재사용하세요.

4. 멱등#

엔드포인트 멱등 키 의미
/v1/images/generations idempotency_key(선택) 동일 사용자 동일 키는 원래 작업 반환
/v1/images/edits idempotency_key(선택) 위와 같음

텍스트 대화 요청은 멱등을 보장하지 않습니다. 네트워크 재시도는 새 과금 요청을 만듭니다.


5. 과금 관련 상태#

상황 동작
잔액 부족 업스트림에 도달하기 전에 402, 비용 발생 없음
요청 도중 실패 예약 전액 반환
작업 실패/취소 예약 전액 반환
스트리밍 시작 후 연결 끊김 이미 전달된 내용 기준으로 정산; 전달량이 0이면 과금하지 않음