Mindlogic Logo
Docs

레퍼런스

에러

요약

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

HTTP 상태 코드

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

에러 응답 형식

json
{
  "detail": {
    "code": 401,
    "message": "Authentication Error - Bearer token is not supplied"
  }
}

자주 발생하는 에러

에러상태원인해결 방법
Authorization header is not supplied401요청에 API 키 없음Authorization: Bearer KEY 또는 x-api-key: KEY 헤더 추가
Bearer token is not supplied401Authorization 헤더 형식 오류Authorization: Bearer YOUR_KEY 형식 사용
Invalid API key401키가 존재하지 않거나 해지됨개발자 설정에서 키 확인
Model 'X' not found404모델 이름 오류 또는 비활성화채팅 모델: /v1/gateway/models/ 확인. 이미지/오디오/비디오: 에러 응답에 사용 가능한 모델이 나열됩니다.
Model 'X' is not an Anthropic model400비Anthropic 모델로 /claude/v1/messages/ 사용비Anthropic 모델은 /chat/completions/ 사용
Model 'X' is not an OpenAI model400비OpenAI 모델로 /responses/ 사용/chat/completions/ 또는 /claude/v1/messages/ 사용
Credit balance exhausted402크레딧 잔액 없음개발자 설정에서 크레딧 충전
Rate limit exceeded429요청 과다지수 백오프 구현
Model 'gpt-5.x-codex' not found400Codex 모델로 /chat/completions/ 사용Codex 모델은 /v1/gateway/responses/에서만 사용 가능
추론 모델이 빈 응답 반환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을 설정했는지 확인하세요:
bash
export ANTHROPIC_AUTH_TOKEN=YOUR_API_KEY  # 올바름
export ANTHROPIC_API_KEY=YOUR_API_KEY     # 커스텀 Base URL에서 잘못됨

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

Anthropic SDK는 Base URL에 /v1/messages를 자동 추가합니다. Base URL이 /claude로 끝나도록 설정하세요:
bash
# 올바름
export ANTHROPIC_BASE_URL=https://factchat-cloud.mindlogic.ai/v1/gateway/claude

# 잘못됨 — SDK가 /v1/gateway/v1/messages/로 POST
export ANTHROPIC_BASE_URL=https://factchat-cloud.mindlogic.ai/v1/gateway

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

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

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

일부 프록시 및 로드 밸런서가 SSE 응답을 버퍼링합니다. 스트리밍이 끊기면:
  • Connection: keep-alive 헤더 설정
  • 클라이언트 측 타임아웃 설정 줄이기
  • 네트워크 관리자에게 프록시 버퍼링 설정 확인 요청
위 방법으로도 문제가 해결되지 않으면, 담당자에게 문의해주세요. 에러 메시지와 요청 정보를 함께 전달해주시면 더 빠르게 도움을 드릴 수 있습니다.

마지막 수정 날짜: Feb 24, 2026

이전

/video/generation