문제 해결
자주 겪는 문제와 해결 방법입니다.
답변이 비어 있는 경우
content가 비어 있거나 null이고 finish_reason이 length라면(Messages는 stop_reason: "max_tokens", Responses는 status: "incomplete"), 모델이 답변을 생성하기 전에 추론에 max_tokens를 모두 사용한 것입니다.
추론과 답변을 모두 생성할 수 있도록 max_tokens를 늘리세요. 어려운 질문은 추론에만 수천 토큰이 사용될 수 있습니다.
모든 요청이 404를 반환하는 경우
Base URL의 /v1 포함 여부를 확인하세요. OpenAI SDK와 대부분의 OpenAI 호환 도구는 https://raon-api.krafton.ai/v1을 사용합니다. Anthropic SDK와 Claude Code는 /v1을 자동으로 추가하므로 https://raon-api.krafton.ai를 사용합니다.
403 model_not_allowed 오류가 발생하는 경우
API 키로 사용할 수 없는 모델 ID를 지정한 경우입니다. 다른 서비스의 모델 이름 대신 raon-1-mini-preview를 사용하세요. 사용할 수 있는 모델 ID는 GET /v1/models로 확인할 수 있습니다.
401 invalid_api_key 오류가 발생하는 경우
요청에 API 키가 포함되어 있는지, 콘솔의 API 키 화면에서 해당 키가 삭제되거나 만료되지 않았는지 확인하세요. Chat Completions와 Responses는 Authorization: Bearer <key> 헤더를 사용하며, Messages는 x-api-key 헤더도 사용할 수 있습니다.
응답이 느리거나 타임아웃이 발생하는 경우
추론과 웹 검색이 포함되면 응답에 몇 분이 걸릴 수 있습니다. 다음 사항을 확인하세요.
- 스트리밍으로 진행 상황을 확인합니다.
- 클라이언트 타임아웃을 10분 이상으로 설정합니다.
- 추론과 답변에 필요한 출력 토큰 수를 충분히 지정합니다.
자세한 내용은 타임아웃을 참고하세요.
429 오류가 발생하는 경우
retry-after에 지정된 시간만큼 기다린 후 재시도하고, 동시 요청 수를 줄이세요. 자세한 내용은 속도 제한을 참고하세요.
이미지나 파일 내용을 인식하지 못하는 경우
모델은 텍스트 입력만 지원합니다. 문서는 텍스트로 변환해 메시지에 포함하세요. 이미지와 오디오는 지원하지 않습니다.
이전 대화 내용을 기억하지 못하는 경우
Raon은 대화 내용을 서버에 저장하지 않습니다. 요청할 때마다 이전 메시지와 모델의 이전 답변을 함께 보내세요. 일반 텍스트 대화에서는 이전 응답의 추론 내용을 생략할 수 있습니다.
Responses API의 출력 항목을 다음 요청에 다시 보낼 때는 reasoning 항목과 관련 출력 항목의 순서를 유지하세요. 자세한 내용은 API 레퍼런스를 참고하세요.
코딩 에이전트가 실행되지 않거나 다른 모델을 사용하는 경우
에이전트 설치 스크립트를 다시 실행하세요. 설치 스크립트가 API 키를 테스트하고 설정을 다시 작성합니다. 수동 설정 방법은 각 에이전트 문서를 참고하세요. Claude Code와 Codex는 raon-claude, raon-codex 명령으로 실행해야 합니다. claude, codex 명령은 기존 설정을 그대로 사용합니다.