오류 코드와 재시도
오류 발생 시 인터페이스는 2xx가 아닌 상태 코드를 반환하며, 응답 본문은 JSON 형식입니다:
{ "error": { "message": "错误描述", "type": "invalid_request_error", "code": "..." }}일반 오류 코드
| HTTP 상태 | 일반 원인 | 권장 처리 방법 |
|---|---|---|
| 400 | 파라미터 오류, 요청 본문 형식 불법 | 파라미터와 JSON 형식 확인 |
| 401 | 키 누락 / 유효하지 않음 | Authorization: Bearer sk-... 확인 |
| 403 | 토큰 비활성화, 모델 그룹 접근 권한 없음 | 콘솔에서 토큰 상태와 그룹 확인 |
| 404 | 모델명이 존재하지 않거나 미공개 | 모델 개요 참조 |
| 413 | 요청 본문 과대(컨텍스트 초과) | messages 간소화 또는 긴 컨텍스트 모델로 교체 |
| 429 | 속도 제한 또는 할당량 부족 | 백오프 후 재시도, 속도 제한과 429 참조 |
| 500 / 502 / 503 | 업스트림 모델 불안정 | 잠시 백오프 후 재시도, 게이트웨이가 자동으로 가용 업스트림으로 전환 |
재시도 권장 사항
- 429 / 5xx에는 지수 백오프 + 지터를 사용하세요: 예) 1초, 2초, 4초, 최대 3–5회;
- 400 / 401 / 403은 확정적 오류로 재시도는 의미가 없으며, 먼저 요청을 수정해야 합니다;
- 멱등성 시나리오(예: 이미지 생성)에서 재제출 전 이전 요청의 최종 상태를 먼저 확인하여 중복 과금을 방지하세요;
- 프로덕션 환경에서는 응답 헤더와
error.message를 기록하여 어느 단계에서 오류가 반환되었는지 추적하기 쉽게 하는 것을 권장합니다.