错误与限制

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

错误响应格式

所有错误遵循统一格式:

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

资源不存在:

{
  "statusCode": 404,
  "statusMessage": "Spark 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 指定的秒数等待。

计划限制

不同计划有不同的资源限制。

Mind 限制

达到限制时的错误:

{
  "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 Key 限制

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

最佳实践

错误处理

始终处理错误:

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(rate limit)与 5xx 错误进行重试
• 使用指数退避
• 设置最大重试次数
• 不要对 4xx 错误重试(429 除外)

监控

追踪你的使用情况:

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

在需要时升级

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

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

查看计划

获取帮助

查看状态

监控我们的服务状态:

• 状态页(即将推出)
• 关注 @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