오류
오류 응답 형식, 상태 코드, 재시도 기준, 타임아웃입니다.
오류 형식
Raon 게이트웨이는 직접 생성한 오류를 API별 응답 형식에 맞춰 반환합니다. Chat Completions, Responses, GET /v1/models의 오류 응답 형식은 다음과 같습니다.
{
"error": {
"message": "Incorrect API key provided.",
"type": "authentication_error",
"param": null,
"code": "invalid_api_key"
}
}Messages에서는 게이트웨이가 생성한 오류를 다음과 같은 Anthropic 형식으로 반환합니다. 이 형식에는 code 필드가 없습니다.
{
"type": "error",
"error": {
"type": "authentication_error",
"message": "Incorrect API key provided."
}
}SDK는 오류 응답을 openai.AuthenticationError, anthropic.RateLimitError 같은 예외로 변환합니다.
모델 서버에서 발생한 입력 검증 오류는 다른 형식으로 전달될 수 있습니다. 예를 들어 Messages 요청에 대한 HTTP 400 응답에도 최상위 type 필드 없이 error.type: "upstream_error"와 error.code: "upstream_http_error"가 포함될 수 있습니다. 예기치 않은 내부 오류도 OpenAI 형식으로 반환될 수 있습니다. Messages의 오류 응답을 처리할 때는 위 예시 외의 형식도 고려해 HTTP 상태 코드와 전체 응답 본문을 확인하세요.
상태 코드
| 상태 코드 | code | 원인 | 재시도 여부 |
|---|---|---|---|
| 400 | invalid_request | 잘못된 JSON 본문, 필수 필드 누락, 지원하지 않는 기능 사용 | 아니요 (요청 수정) |
| 400 | unsupported_tool | Raon이 실행하지 않는 도구 사용 (예: code_interpreter) | 아니요 |
| 400 | token_limit_exceeded | 단일 요청의 분당 토큰 한도 초과 | 아니요 |
| 400 | — | 입력과 max_tokens의 합이 컨텍스트 윈도우 초과 | 아니요 (입력 축소) |
| 401 | invalid_api_key | API 키 누락, 오류, 비활성화 또는 만료 | 아니요 |
| 402 | insufficient_credit, spend_limit_exceeded | 크레딧 부족 또는 월 지출 한도 도달 | 아니요 |
| 403 | model_not_allowed | 잘못된 모델 ID 또는 API 키로 사용할 수 없는 모델 | 아니요 |
| 404 | — | 제공하지 않는 경로 (주로 Base URL의 /v1 누락 또는 중복) | 아니요 |
| 413 | payload_too_large | 요청 본문 크기 28 MiB 초과 | 아니요 |
| 429 | rate_limit_exceeded, overloaded | 속도 제한 초과 또는 서비스 과부하 | 예 (retry-after 이후) |
| 500 | — | Raon 내부 오류 | 예 (지수 백오프) |
| 502 | upstream_error | 모델 서버 오류 또는 응답 시간 초과 | 예 (지수 백오프) |
재시도할 때는 지수 백오프로 대기 시간을 점차 늘리고, 재시도 횟수에 상한을 두세요. 429를 제외한 4xx 오류는 같은 요청을 다시 보내도 같은 이유로 실패하므로 재시도하지 마세요.
이번 프리뷰의 모델 이용 요금은 0원입니다. 다만 조직의 크레딧이나 지출 한도 정책에 따라 HTTP 402 오류가 발생할 수 있습니다. 이 경우 프리뷰 운영자에게 문의하세요.
스트리밍 중 오류
스트리밍 응답은 시작 시점에 이미 상태 코드 200을 반환하므로, 이후 발생한 오류는 스트림 안의 이벤트로 전달됩니다.
| API | 오류 이벤트 |
|---|---|
| Chat Completions | {"error": {...}}를 포함한 data: 행 |
| Responses | event: error |
| Messages | Anthropic 형식의 event: error |
SDK는 스트림을 읽는 중에 이 이벤트를 받으면 예외를 발생시킵니다. 오류 이전에 받은 텍스트는 완전한 답변이 아니므로, 전체 답변이 필요하면 요청을 다시 보내세요.
타임아웃
추론이나 웹 검색이 포함되면 응답까지 몇 분이 걸릴 수 있습니다. Raon은 요청당 최대 10분까지 처리하므로, 클라이언트 타임아웃도 10분 이상으로 설정하세요. OpenAI SDK와 Anthropic SDK의 기본 타임아웃은 10분입니다.
- 스트리밍을 사용하면 진행 상황을 바로 확인할 수 있고 연결도 유지됩니다. 웹 검색 중처럼 10초 동안 전송할 데이터가 없으면 Raon이
: ping주석 행을 보냅니다. SSE 클라이언트는 이 행을 무시합니다. - 클라이언트 연결이 끊기면 Raon도 요청 처리를 중단합니다.
- 요청에는
Content-Length헤더가 필요합니다. SDK와 curl은 이 헤더를 자동으로 추가합니다. 이 헤더 없이 chunked 방식으로 전송하면 411 오류가 반환됩니다.
문의 시 필요한 정보
문제를 문의할 때는 요청 시각, 응답 헤더의 x-request-id, 상태 코드, 오류 응답 본문을 함께 전달해 주세요. x-request-id는 Raon이 생성하는 요청 추적용 UUID이며 스트리밍 응답에도 포함됩니다. 요청에 같은 이름의 헤더를 보내도 해당 값은 사용하지 않습니다.