오류 및 제한

API 오류, 속도 제한 및 요금제 제한 이해하기.

오류 응답 형식

모든 오류는 일관된 형식을 따릅니다:

{
  "statusCode": 400,
  "statusMessage": "Name is required",
  "message": "Name is required",
  "url": "/api/v1/sparks",
  "error": true
}

항상 프로그램적 처리를 위해 statusCode에 의존하고, 사람이 읽을 수 있는 이유를 위해 statusMessage (또는 message)를 사용하세요. url 및 error 필드는 기본 프레임워크의 편의 메타데이터입니다.

HTTP 상태 코드

2xx 성공

4xx 클라이언트 오류

5xx 서버 오류

일반 오류

400 잘못된 요청

필수 필드 누락:

{
  "statusCode": 400,
  "statusMessage": "Name is required"
}

잘못된 입력:

{
  "statusCode": 400,
  "statusMessage": "File too large: document.pdf (55.2MB). Maximum size is 50MB."
}

401 인증되지 않음

API 키 누락:

{
  "statusCode": 401,
  "statusMessage": "Unauthorized"
}

해결책: Authorization 헤더를 포함하세요:

-H "Authorization: Bearer minds_your_api_key"

403 금지됨

요금제 한도 초과:

{
  "statusCode": 403,
  "statusMessage": "Individual plan limit reached",
  "message": "Individual plan limit reached",
  "url": "/api/v1/sparks",
  "error": true,
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "sparks",
    "currentPlan": "premium",
    "limit": 100,
    "current": 100
  }
}

접근 거부:

{
  "statusCode": 403,
  "statusMessage": "Access denied"
}

404 찾을 수 없음

리소스가 존재하지 않음:

{
  "statusCode": 404,
  "statusMessage": "Spark not found"
}

415 지원되지 않는 미디어 유형

잘못된 Content-Type:

{
  "statusCode": 415,
  "statusMessage": "Unsupported Content-Type. Use application/json for links or multipart/form-data for files"
}

해결책: 올바른 Content-Type 헤더를 사용하세요:

• JSON 요청의 경우 application/json
• 파일 업로드의 경우 multipart/form-data

429 요청이 너무 많음

속도 제한 초과:

{
  "statusCode": 429,
  "statusMessage": "Too many requests. Please try again later."
}

속도 제한

v1 API는 인증된 계정별 고정 시간 창 제한을 적용합니다. 배포 기본값은 분당 300개 요청이지만 설정으로 변경될 수 있습니다. 항상 RateLimit-Limit와 RateLimit-Remaining을 읽고, 429 이후에는 Retry-After에 표시된 초만큼 기다리세요.

요금제 제한

다양한 요금제는 서로 다른 리소스 제한을 가지고 있습니다.

Minds 제한

한도 초과 시 오류:

{
  "statusCode": 403,
  "statusMessage": "Individual plan limit reached",
  "message": "Individual plan limit reached",
  "url": "/api/v1/sparks",
  "error": true,
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "sparks",
    "currentPlan": "premium",
    "limit": 100,
    "current": 100
  }
}

지식 업로드 제한

• 파일 크기: 파일당 최대 50MB (모든 요금제)
• 저장소: 현재 시행되는 명시적인 저장소 제한 없음

API 키 제한

• 최대 키: 현재 적용되는 상한이 없습니다.

모범 사례

오류 처리

항상 오류를 처리하세요:

try {
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });

  if (!response.ok) {
    const error = await response.json();
    console.error(`Error ${error.statusCode}: ${error.message}`);
    // Handle specific errors
    if (error.statusCode === 429) {
      // Implement retry logic
    }
  }

  const result = await response.json();
  return result;
} catch (error) {
  console.error('Network error:', error);
}

재시도 로직

스마트 재시도를 구현하세요:

• 429 (속도 제한) 및 5xx 오류에서 재시도
• 지수 백오프 사용
• 최대 재시도 횟수 설정
• 4xx 오류에서는 재시도하지 마세요 (429 제외)

모니터링

사용량 추적:

• 속도 제한 헤더 기록
• 오류 비율 모니터링
• 반복되는 오류에 대한 알림 설정
• 응답 시간 추적

필요 시 업그레이드

다음과 같은 경우 요금제를 업그레이드하세요:

• 속도 제한에 자주 걸림
• 더 많은 Minds가 필요함
• 더 큰 파일 업로드가 필요함
• 우선 지원을 원함

요금제 보기

도움 받기

상태 확인

우리 서비스 상태 모니터링:

• 상태 페이지 (곧 출시 예정)
• 업데이트를 위해 @mindsai_co 팔로우

지원 문의

다음과 같은 문제가 발생하면:

• 지속적인 500 오류
• 잘못된 속도 제한
• 예기치 않은 동작

연락하세요:

• 피드백 양식
• 이메일: [email protected]

문서 검토

• API 개요
• 인증
• Sparks API
• Knowledge API
• Chat API

상태 코드 참조

모든 HTTP 상태 코드에 대한 빠른 참조:

2xx Success
├─ 200 OK
└─ 201 Created

4xx Client Error
├─ 400 Bad Request
├─ 401 Unauthorized
├─ 403 Forbidden
├─ 404 Not Found
├─ 415 Unsupported Media Type
└─ 429 Too Many Requests

5xx Server Error
├─ 500 Internal Server Error
└─ 503 Service Unavailable