エラーと制限

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ヘッダーを使用してください：

• application/jsonはJSONリクエスト用
• multipart/form-dataはファイルアップロード用

429 リクエストが多すぎます

レート制限を超えました:

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

レート制限

v1 APIは認証済みアカウントごとの固定ウィンドウ制限を適用します。デプロイ時の既定値は1分あたり300リクエストですが、設定で変更できます。RateLimit-LimitとRateLimit-Remainingを確認し、429の後はRetry-Afterで指定された秒数だけ待機してください。

プラン制限

異なるプランには異なるリソース制限があります。

マインド制限

制限に達した際のエラー:

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