오류와 속도 제한
적용 대상: 모든
/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분 창을 사용합니다. 해석 순서:
- Key 수준 재정의(콘솔 설정)
- 모델 수준 기본값
- 플랜 기본값
- 시스템 폴백: 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이면 과금하지 않음 |