자주 발생하는 오류

각 도구 가이드에는 해당 도구에 특화된 오류만 정리되어 있습니다. 아래 오류는 어떤 도구에서든 발생할 수 있습니다. 먼저 오류의 상태 코드나 키워드를 확인한 뒤 아래 표에서 찾아보세요:

오류	원인	해결 방법
401 / invalid api key	키가 불완전하거나 앞뒤에 공백이 있거나, 마스킹된 표시 값을 복사한 경우	API Keys로 이동해 복사 아이콘을 클릭하고 전체 HiAPI API 키를 다시 복사하세요
오류에 잔액, 할당량, 지출 한도가 언급됨	계정 잔액이 부족하거나 이 키의 지출 한도를 모두 사용한 경우	계정 잔액에서 충전하거나 API Keys 페이지에서 이 키의 지출 한도를 높이세요
403	이 키에 해당 모델 권한이 없음	키의 그룹과 권한을 확인하세요. 인증을 참고하세요
404 / model not available	Base URL에 /v1이 더 있거나 빠졌거나, 모델 이름에 오타가 있음	Base URL 및 프로토콜에서 URL을 확인하고, 텍스트 모델 목록에서 모델 이름을 복사하세요
400 does not support this endpoint	이 모델이 도구에 선택된 프로토콜을 지원하지 않음	다른 프로토콜(예: Claude에는 Anthropic Messages)을 시도하거나 다른 모델로 바꾸세요
400 stream must be true / 계속 로딩만 됨	모델이 스트리밍 전용인데 도구가 비스트리밍 요청을 보냄	도구에서 스트리밍을 켜세요. 도구의 “Check” 또는 “Test connection” 버튼에서 이 오류가 나오면 무시하고 실제 채팅으로 확인하세요
429	요청이나 동시 실행이 너무 많음	기다렸다가 재시도하고, 동시에 실행하는 작업 수를 줄이세요. 오류에 할당량이 언급되면 위의 “잔액, 할당량” 행을 따르세요
500 / 502 / 503	모델 서비스가 일시적으로 실패함	1~2분 기다렸다가 재시도하세요. 계속되면 먼저 다른 모델을 시도한 뒤 문의하세요
타임아웃 / 응답 중단	네트워크나 프록시가 장시간 연결을 차단함	api.hiapi.ai에 대한 네트워크와 프록시 규칙을 확인한 뒤 재시도하세요

재시도 전에 요청 로그 확인

서버에서는 에이전트 작업이 이미 끝났는데 도구의 연결만 끊겼을 수 있습니다. 재시도하기 전에 요청 로그에서 이 요청이 성공했는지, 비용이 얼마였는지 확인해 같은 작업에 두 번 결제하지 마세요.

그래도 해결되지 않으면

문의하기에서 아래 정보와 함께 티켓을 제출하세요. 문제를 더 빨리 찾는 데 도움이 됩니다:

• 오류가 발생한 시각(분 단위까지)
• 사용한 도구와 버전. 예: Claude Code 2.1.284
• 모델 이름과 Base URL
• 원본 오류 문구 또는 스크린샷

스크린샷을 찍기 전에 API 키를 가리고, 고객지원을 포함해 누구에게도 키를 보내지 마세요.