오류 Reference
API 오류는 각 호환 경로의 생태계 형식을 따라요. 상태 코드 의미는 두 경로가 같습니다.
오류 응답 형식
Claude 호환 경로 (Anthropic 형식)
error response
json
{ "type": "error", "error": { "type": "authentication_error", "message": "인증에 실패했습니다." }}Codex 호환 경로 (OpenAI 형식)
error response
json
{ "error": { "message": "인증에 실패했습니다.", "type": "authentication_error", "code": "invalid_api_key" }}상태 코드 요약
| 코드 | 의미 | 먼저 확인할 것 |
|---|---|---|
400 | 요청 형식 오류 | model · messages · header 형식을 확인해요. |
401 | 인증 실패 | 키 값과 공백·따옴표 여부를 확인해요. |
403 | 권한 또는 정책 차단 | 키 상태 · 플랜 · 허용 모델 범위를 확인해요. |
429 | 요청량 제한 | 백오프를 적용해 재시도해요. Retry-After 헤더를 우선 따라요. |
500 | 서버 내부 오류 | 재시도 전에 요청 ID와 시간을 기록해 두세요. |
코드별 자세한 점검 순서는 오류 코드 문서가 기준이에요. 증상이 애매하다면 문제 해결에서 오류 메시지로 검색해 보세요.
Gemini 연결 문제
구매가 준비 중이면 API 사용 가능 상태로 간주하지 마세요. 사용 가능 상태에서 401/403은 Gemini 키와 인증 헤더, 404는 해당 endpoint와 공개 모델 ID, 429는 잔액·사용 제한과 재시도 간격을 확인하세요. HTTP 5xx는 외부 서비스 상태를 확인하고, 같은 요청을 무한 재시도하지 마세요. 문의에는 키 대신 요청 ID와 상태 코드만 전달하세요.
이 문서가 도움이 되었나요?