错误与限制

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

错误响应格式

所有错误遵循统一格式:

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

在程序化处理时始终依赖 statusCode,并使用 statusMessage(或 message)获取可读原因。url 和 error 字段是底层框架提供的便利元数据。

HTTP 状态码

2xx 成功

4xx 客户端错误

5xx 服务器错误

常见错误

400 Bad Request

缺少必填字段:

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

输入无效:

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

401 Unauthorized

缺少 API Key:

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

解决方案: 包含 Authorization header:

-H "Authorization: Bearer minds_your_api_key"

403 Forbidden

达到计划限制:

{
  "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
  }
}

访问被拒绝:

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

404 Not Found

资源不存在:

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

415 Unsupported Media Type

错误的 Content-Type:

{
  "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:

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

Rate Limit

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

计划限制

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

Mind 限制示例

达到限制时的错误:

{
  "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 个的受众上发起受众验证，会返回 422 及代码 AUDIENCE_TOO_SMALL。受众规模超过你的方案在单个研究中允许的上限时，会以上文所述的标准方案限制错误拒绝。

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

最佳实践

错误处理

始终处理错误:

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
• 需要更大的文件上传
• 需要优先支持

查看计划

获取帮助

查看状态

监控我们的服务状态:

• Minds 服务状态
• 关注 @mindsai_co 获取更新

联系支持

如果你遇到:

• 持续的 500 错误
• 不正确的限流
• 异常行为

联系我们:

• 反馈表单
• 邮箱:[email protected]

查阅文档

• API 概览
• 身份验证
• Minds 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