에러

에러가 발생했을 때 당황하지 마세요! 🙌

이 페이지에서는 마인드로직 운영 API Gateway에서 발생할 수 있는 에러 코드와 응답 형식을 정리하고, 증상별 해결 방법을 안내합니다. 대부분의 에러는 간단한 설정 변경으로 해결할 수 있습니다.

HTTP 상태 코드

상태	의미
`200`	성공
`400`	잘못된 요청 — 유효하지 않은 파라미터 또는 엔드포인트에 맞지 않는 모델 타입
`401`	인증 실패 — API 키 누락 또는 유효하지 않음
`402`	결제 필요 — 크레딧 잔액 소진
`404`	찾을 수 없음 — 모델을 찾을 수 없거나 엔드포인트 경로 오류
`429`	요청 과다 — 속도 제한 초과
`500`	내부 서버 오류 — 업스트림 제공업체 오류

에러 응답 형식

자주 발생하는 에러

에러	상태	원인	해결 방법
`Authorization header is not supplied`	401	요청에 API 키 없음	`Authorization: Bearer KEY` 또는 `x-api-key: KEY` 헤더 추가
`Bearer token is not supplied`	401	`Authorization` 헤더 형식 오류	`Authorization: Bearer YOUR_KEY` 형식 사용
`Invalid API key`	401	키가 존재하지 않거나 해지됨	개발자 설정에서 키 확인
`Model 'X' not found`	404	모델 이름 오류 또는 비활성화	채팅 모델: `/v1/gateway/models/` 확인. 이미지/오디오/비디오: 에러 응답에 사용 가능한 모델이 나열됩니다.
`Model 'X' is not an Anthropic model`	400	비Anthropic 모델로 `/claude/v1/messages/` 사용	비Anthropic 모델은 `/chat/completions/` 사용
`Model 'X' is not an OpenAI model`	400	비OpenAI 모델로 `/responses/` 사용	`/chat/completions/` 또는 `/claude/v1/messages/` 사용
`Credit balance exhausted`	402	크레딧 잔액 없음	개발자 설정에서 크레딧 충전
`Rate limit exceeded`	429	요청 과다	지수 백오프 구현
`Model 'gpt-5.x-codex' not found`	400	Codex 모델로 `/chat/completions/` 사용	Codex 모델은 `/v1/gateway/responses/`에서만 사용 가능
`reasoning_effort` + `tools` 동시 사용 시 400	400	일부 모델이 `reasoning_effort`와 도구 호출을 동시에 지원하지 않음	게이트웨이가 자동으로 `reasoning_effort`를 제거하고 재시도합니다. 직접 처리가 필요한 경우 `reasoning_effort`를 제거하거나 Responses API를 사용하세요
추론 모델이 빈 응답 반환	200	낮은 `max_tokens` — 추론 토큰이 전체 예산을 소비	추론 모델(GPT-5 시리즈, Gemini 2.5 Pro)은 `max_tokens: 16000+` 사용. 일부 모델(`gpt-5`, `gpt-5-mini`, `gpt-5.1-chat-latest`, `gpt-5.2-chat-latest`)은 `temperature: 1`도 필요

증상별 트러블슈팅

Claude Code에서 401 오류가 발생하나요?

Claude Code는 기본적으로 x-api-key 헤더를 전송합니다. ANTHROPIC_API_KEY가 아닌 ANTHROPIC_AUTH_TOKEN을 설정했는지 확인하세요:

Anthropic SDK에서 404 오류가 발생하나요?

Anthropic SDK는 Base URL에 /v1/messages를 자동 추가합니다. Base URL이 /claude로 끝나도록 설정하세요:

모델 이름이 맞는데도 찾을 수 없나요?

GET /v1/gateway/models/로 정확한 모델 이름 확인
개발자 설정에서 해당 모델이 조직에 활성화되어 있는지 확인
API 키가 올바른 조직에 속하는지 확인

스트리밍이 예상치 않게 중단되나요?

일부 프록시 및 로드 밸런서가 SSE 응답을 버퍼링합니다. 스트리밍이 끊기면:

Connection: keep-alive 헤더 설정
클라이언트 측 타임아웃 설정 줄이기
네트워크 관리자에게 프록시 버퍼링 설정 확인 요청

위 방법으로도 문제가 해결되지 않으면, 담당자에게 문의해주세요. 에러 메시지와 요청 정보를 함께 전달해주시면 더 빠르게 도움을 드릴 수 있습니다.

마지막 수정 날짜: Apr 09, 2026

멤버 그룹 관리 API