---
title: "오류 및 제한"
description: "API 오류, 상태 코드 및 요금제 기반 리소스 제한 이해하기."
---

# 오류 및 제한

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

## 오류 응답 형식

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

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

<table>
<thead>
  <tr>
    <th>
      필드
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        statusCode
      </code>
    </td>
    
    <td>
      HTTP 상태 코드
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        statusMessage
      </code>
    </td>
    
    <td>
      사람이 읽을 수 있는 오류 설명 (핸들러에 의해 오류별로 설정됨 , 유효성 검사 오류의 경우 특정 문제, 예: <code>
        "Mind not found"
      </code>
      
       또는 <code>
        "Invalid Mind ID format"
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        message
      </code>
    </td>
    
    <td>
      v1 오류에 대한 <code>
        statusMessage
      </code>
      
      와 동일한 내용. 디버그 빌드의 <code>
        5xx
      </code>
      
       응답에서 스택/추가 컨텍스트를 위해 예약됨.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        url
      </code>
    </td>
    
    <td>
      요청 경로 (Nuxt H3에 의해 추가됨)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        error
      </code>
    </td>
    
    <td>
      오류 응답에 대한 <code>
        true
      </code>
      
       (Nuxt H3에 의해 추가됨)
    </td>
  </tr>
</tbody>
</table>

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

## HTTP 상태 코드

### 2xx 성공

<table>
<thead>
  <tr>
    <th>
      코드
    </th>
    
    <th>
      상태
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      200
    </td>
    
    <td>
      OK
    </td>
    
    <td>
      요청 성공
    </td>
  </tr>
  
  <tr>
    <td>
      201
    </td>
    
    <td>
      생성됨
    </td>
    
    <td>
      리소스가 성공적으로 생성됨 (예: <code>
        POST /minds
      </code>
      
      , <code>
        POST /minds/{id}/knowledge
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      202
    </td>
    
    <td>
      수락됨
    </td>
    
    <td>
      비동기 처리를 위해 요청이 수락됨 (예: <code>
        POST /minds/{id}/knowledge
      </code>
      
      와 <code>
        keywords
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      204
    </td>
    
    <td>
      콘텐츠 없음
    </td>
    
    <td>
      요청 성공, 응답 본문 없음 (예: <code>
        DELETE /minds/{id}/knowledge/{itemId}
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

### 4xx 클라이언트 오류

<table>
<thead>
  <tr>
    <th>
      코드
    </th>
    
    <th>
      상태
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      400
    </td>
    
    <td>
      잘못된 요청
    </td>
    
    <td>
      잘못된 요청 매개변수
    </td>
  </tr>
  
  <tr>
    <td>
      401
    </td>
    
    <td>
      인증되지 않음
    </td>
    
    <td>
      API 키가 없거나 잘못됨
    </td>
  </tr>
  
  <tr>
    <td>
      403
    </td>
    
    <td>
      금지됨
    </td>
    
    <td>
      접근 거부 또는 요금제 한도 초과
    </td>
  </tr>
  
  <tr>
    <td>
      404
    </td>
    
    <td>
      찾을 수 없음
    </td>
    
    <td>
      리소스가 존재하지 않음
    </td>
  </tr>
  
  <tr>
    <td>
      415
    </td>
    
    <td>
      지원되지 않는 미디어 유형
    </td>
    
    <td>
      잘못된 Content-Type 헤더
    </td>
  </tr>
  
  <tr>
    <td>
      429
    </td>
    
    <td>
      요청이 너무 많음
    </td>
    
    <td>
      속도 제한 초과
    </td>
  </tr>
</tbody>
</table>

### 5xx 서버 오류

<table>
<thead>
  <tr>
    <th>
      코드
    </th>
    
    <th>
      상태
    </th>
    
    <th>
      설명
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      500
    </td>
    
    <td>
      내부 서버 오류
    </td>
    
    <td>
      서버 측 오류
    </td>
  </tr>
  
  <tr>
    <td>
      503
    </td>
    
    <td>
      서비스 사용 불가
    </td>
    
    <td>
      서비스가 일시적으로 사용 불가
    </td>
  </tr>
</tbody>
</table>

## 일반 오류

### 400 잘못된 요청

**필수 필드 누락:**

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

**잘못된 입력:**

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

### 401 인증되지 않음

**API 키 누락:**

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

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

```bash
-H "Authorization: Bearer minds_your_api_key"
```

### 403 금지됨

**요금제 한도 초과:**

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

**접근 거부:**

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

### 404 찾을 수 없음

**리소스가 존재하지 않음:**

```json
{
  "statusCode": 404,
  "statusMessage": "Mind not found"
}
```

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

**잘못된 Content-Type:**

```json
{
  "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 요청이 너무 많음

**속도 제한 초과:**

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

## 속도 제한

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

## 요금제 제한

현재 공개 기본값은 생성된 [플랜 제한 표](/docs/api/overview)를 참조하세요. 계약별 재정의는 다를 수 있으므로 인증된 오류의 `data.limit`와 `data.current`가 해당 요청의 권위 있는 값입니다. Individual 플랜은 API payload에서 `"premium"`으로 표시됩니다.

### Mind 제한 예시

**한도 초과 시 오류:**

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

### 지식 업로드 제한

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

### API 키 제한

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

## 모범 사례

### 오류 처리

**항상 오류를 처리하세요:**

```javascript
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가 필요함
- 더 큰 파일 업로드가 필요함
- 우선 지원을 원함

[요금제 보기](/settings?tab=subscription)

## 도움 받기

### 상태 확인

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

- [Minds 서비스 상태](https://uptime.getminds.ai)
- 업데이트를 위해 [@mindsai_co](https://x.com/mindsai_co) 팔로우

### 지원 문의

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

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

연락하세요:

- 피드백 양식
- 이메일: [support@getminds.ai](mailto:support@getminds.ai)

### 문서 검토

- [API 개요](/docs/api/overview)
- [인증](/docs/api/authentication)
- [Minds API](/docs/api/minds)
- [Knowledge API](/docs/api/knowledge)
- [Chat API](/docs/api/chat)

## 상태 코드 참조

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

```text
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
```