---
title: "错误与限制"
description: "理解 API 错误、状态码以及基于计划的资源限制。"
---

# 错误与限制

理解 API 错误、rate limit 以及计划限制。

## 错误响应格式

所有错误遵循统一格式:

```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>
      
       内容相同。在 debug 构建的 <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>
      Created
    </td>
    
    <td>
      资源创建成功(例如 <code>
        POST /minds
      </code>
      
      、<code>
        POST /minds/{id}/knowledge
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      202
    </td>
    
    <td>
      Accepted
    </td>
    
    <td>
      请求已接受,正在异步处理(例如带有 <code>
        keywords
      </code>
      
       的 <code>
        POST /minds/{id}/knowledge
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      204
    </td>
    
    <td>
      No Content
    </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>
      Bad Request
    </td>
    
    <td>
      请求参数无效
    </td>
  </tr>
  
  <tr>
    <td>
      401
    </td>
    
    <td>
      Unauthorized
    </td>
    
    <td>
      API key 缺失或无效
    </td>
  </tr>
  
  <tr>
    <td>
      403
    </td>
    
    <td>
      Forbidden
    </td>
    
    <td>
      访问被拒绝或达到计划限制
    </td>
  </tr>
  
  <tr>
    <td>
      404
    </td>
    
    <td>
      Not Found
    </td>
    
    <td>
      资源不存在
    </td>
  </tr>
  
  <tr>
    <td>
      415
    </td>
    
    <td>
      Unsupported Media Type
    </td>
    
    <td>
      Content-Type header 错误
    </td>
  </tr>
  
  <tr>
    <td>
      422
    </td>
    
    <td>
      Unprocessable Entity
    </td>
    
    <td>
      请求格式正确但无法执行，例如在已就绪 Minds 少于 10 个的受众上发起验证（<code>
        AUDIENCE_TOO_SMALL
      </code>
      
      ）
    </td>
  </tr>
  
  <tr>
    <td>
      429
    </td>
    
    <td>
      Too Many Requests
    </td>
    
    <td>
      超过 rate limit
    </td>
  </tr>
</tbody>
</table>

### 5xx 服务器错误

<table>
<thead>
  <tr>
    <th>
      状态码
    </th>
    
    <th>
      状态
    </th>
    
    <th>
      说明
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      500
    </td>
    
    <td>
      Internal Server Error
    </td>
    
    <td>
      服务器端错误
    </td>
  </tr>
  
  <tr>
    <td>
      503
    </td>
    
    <td>
      Service Unavailable
    </td>
    
    <td>
      服务暂不可用
    </td>
  </tr>
</tbody>
</table>

## 常见错误

### 400 Bad Request

**缺少必填字段:**

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

**输入无效:**

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

### 401 Unauthorized

**缺少 API Key:**

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

**解决方案:** 包含 `Authorization` header:

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

### 403 Forbidden

**达到计划限制:**

```json
{
  "statusCode": 403,
  "statusMessage": "Starter plan limit reached",
  "message": "Starter 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 Not Found

**资源不存在:**

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

### 415 Unsupported Media Type

**错误的 Content-Type:**

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

**解决方案:** 使用正确的 `Content-Type` header:

- JSON 请求使用 `application/json`
- 文件上传使用 `multipart/form-data`

### 429 Too Many Requests

**超过 rate limit:**

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

## Rate Limit

v1 API 按已认证账户执行固定时间窗限流。部署默认值为每分钟 300 个请求，但可由运营配置调整。请始终读取 `RateLimit-Limit` 和 `RateLimit-Remaining`；收到 `429` 后，按 `Retry-After` 指定的秒数等待。

## 计划限制

请查看生成的[套餐限制表](/docs/api/overview)了解当前公共默认值。合同覆盖值可能不同，因此认证错误中的 `data.limit` 和 `data.current` 是该请求的权威值。Starter 套餐在 API payload 中表示为 `"premium"`。

### Mind 限制示例

**达到限制时的错误:**

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

### 知识上传限制

- **文件大小:** 每个文件最大 50MB(所有计划)
- **存储:** 目前未强制执行明确的存储限制

### API Key 限制

- **最大 Key 数量:** 目前未强制执行任何上限。

## 受众验证失败

在已就绪 Minds 少于 10 个的受众上发起[受众验证](/docs/api/audiences)，会返回 `422` 及代码 `AUDIENCE_TOO_SMALL`。受众规模超过你的方案在单个研究中允许的上限时，会以上文所述的标准方案限制错误拒绝。

成功发起后，验证会在后台运行，因此大多数失败并不是 HTTP 错误。请改为读取验证批次的 `failure` 字段。批次可能以下列代码之一结束：

<table>
<thead>
  <tr>
    <th>
      代码
    </th>
    
    <th>
      含义
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        AUDIENCE_TOO_SMALL
      </code>
    </td>
    
    <td>
      受众的已就绪 Minds 少于 10 个。发起验证时也会以 <code>
        422
      </code>
      
       返回
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        MINDS_NEED_RETRAINING
      </code>
    </td>
    
    <td>
      受众中的 Minds 需要重新训练后才能作答
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        NOT_ENOUGH_QUESTIONS
      </code>
    </td>
    
    <td>
      适合该受众的问题少于 8 个，因此没有提问
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        NOT_ENOUGH_RESPONSES
      </code>
    </td>
    
    <td>
      运行所需的合成回答多于你的剩余数量
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        NO_FITTING_SURVEY
      </code>
    </td>
    
    <td>
      没有与该受众匹配的已发布调查
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        NO_USABLE_SURVEY
      </code>
    </td>
    
    <td>
      没有任何调查可以验证该受众
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        NO_SCORE
      </code>
    </td>
    
    <td>
      没有任何调查能为该受众评分
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        RUNS_REFUSED
      </code>
    </td>
    
    <td>
      无法启动验证运行
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        SURVEY_NOT_FOUND
      </code>
    </td>
    
    <td>
      找不到指定的调查
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        SURVEY_FILES_UNREADABLE
      </code>
    </td>
    
    <td>
      无法读取上传的调查文件
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        SURVEY_RESULTS_NOT_FOUND
      </code>
    </td>
    
    <td>
      上传的文件中没有可供对照的已发布结果
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        VALIDATION_TOO_LARGE
      </code>
    </td>
    
    <td>
      该验证需要超过 30,000 个回答
    </td>
  </tr>
</tbody>
</table>

## 最佳实践

### 错误处理

**始终处理错误:**

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

  const text = await response.text();
  let result = null;
  if (text) {
    try {
      result = JSON.parse(text);
    } catch {
      if (response.ok) throw new Error('Expected a JSON response');
    }
  }
  if (!response.ok) {
    throw Object.assign(new Error(result?.statusMessage || result?.message || `HTTP ${response.status}`), {
      status: response.status,
      data: result?.data,
      retryAfter: response.headers.get('Retry-After')
    });
  }
  return result;
}
```

### 重试逻辑

**实现智能重试:**

- 读取遇到暂时性的 `429` 或 `5xx` 响应时，可使用有次数限制的指数退避重试，并遵守 `Retry-After`。只有端点明确支持幂等性时才能重试写入，且必须保留相同的键和请求体。超时后若无法确认结果，应先检查已有资源或任务，再决定是否重新提交。
- 使用指数退避
- 设置最大重试次数
- 不要对 `4xx` 错误重试(429 除外)

### 监控

**追踪你的使用情况:**

- 记录 rate limit header
- 监控错误率
- 为重复出现的错误设置告警
- 追踪响应时间

### 在需要时升级

如果你遇到以下情况,请升级计划:

- 频繁触发 rate limit
- 需要更多 mind
- 需要更大的文件上传
- 需要优先支持

[查看计划](/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
```